<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>HyperSQL User Guide</title>
<link href="../docbook.css" type="text/css" rel="stylesheet">
<meta content="DocBook XSL-NS Stylesheets V1.76.1" name="generator">
<meta name="keywords" content="Hsqldb, HyperSQL, Database, JDBC, Java">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="book" title="HyperSQL User Guide">
<div class="titlepage">
<div>
<div>
<h1 class="title">
<a name="guide"></a>HyperSQL User Guide</h1>
</div>
<div>
<h2 class="subtitle">HyperSQL Database Engine (HSQLDB) 2.3</h2>
</div>
<table xmlns:xi="http://www.w3.org/2001/XInclude" class="titlead" cellspacing="0">
<tr>
<td>
<div>
<div class="authorgroup">
<div class="editor">
<h4 class="editedby">Edited by</h4>
<h3 class="editor">
<span class="orgname">The HSQL Development Group</span>
</h3>
</div>
<div class="editor">
<h4 class="editedby">Edited by</h4>
<h3 class="editor">
<span class="firstname">Blaine</span> <span class="surname">Simpson</span>
</h3>
<div class="affiliation">
<span class="orgname">The HSQL Development Group<br>
</span>
</div>
</div>
<div class="editor">
<h4 class="editedby">Edited by</h4>
<h3 class="editor">
<span class="firstname">Fred</span> <span class="surname">Toussi</span>
</h3>
<div class="affiliation">
<span class="orgname">The HSQL Development Group<br>
</span>
</div>
</div>
</div>
</div>
<div>
<div class="legalnotice" title="Legal Notice">
<a name="N1003A"></a>
<p>Copyright 2002-2013 The HSQL Development Group. Permission is
      granted to distribute this document without any alteration under the
      terms of the HSQLDB license. You are not allowed to distribute or
      display this document on the web in an altered form.</p>
</div>
</div>
<div>
<p class="pubdate">2014-02-13 18:21:41-0500</p>
</div>
</td><td class="sponsorad">
<div xml:base="../doc-src/branding-frag.xhtml" class="branding">
<img src="../images/hypersql_logo.png"></div>
</td>
</tr>
</table>
</div>
<hr>
</div>
<div class="toc">
<p>
<b>Table of Contents</b>
</p>
<dl>
<dt>
<span class="preface"><a href="#book-pref">Preface</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#altformats-sect">Available formats for this document</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="chapter"><a href="#running-chapt">1. Running and Using HyperSQL</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#N100CF">Introduction</a></span>
</dt>
<dt>
<span class="section"><a href="#rgc_hsqldb_jar">The HSQLDB Jar</a></span>
</dt>
<dt>
<span class="section"><a href="#rgc_access_tools">Running Database Access Tools</a></span>
</dt>
<dt>
<span class="section"><a href="#rgc_hsqldb_db">A HyperSQL Database</a></span>
</dt>
<dt>
<span class="section"><a href="#rgc_inprocess">In-Process Access to Database Catalogs</a></span>
</dt>
<dt>
<span class="section"><a href="#rgc_server_modes">Server Modes</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#rgc_hsql_server">HyperSQL HSQL Server</a></span>
</dt>
<dt>
<span class="section"><a href="#rgc_http_server">HyperSQL HTTP Server</a></span>
</dt>
<dt>
<span class="section"><a href="#rgc_http_servlet">HyperSQL HTTP Servlet</a></span>
</dt>
<dt>
<span class="section"><a href="#rgc_connecting_db">Connecting to a Database Server</a></span>
</dt>
<dt>
<span class="section"><a href="#rgc_security">Security Considerations</a></span>
</dt>
<dt>
<span class="section"><a href="#rgc_multiple_db">Using Multiple Databases</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#rgc-data-access">Accessing the Data</a></span>
</dt>
<dt>
<span class="section"><a href="#rgc_closing_db">Closing the Database</a></span>
</dt>
<dt>
<span class="section"><a href="#rgc_new_db">Creating a New Database</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="chapter"><a href="#sqlgeneral-chapt">2. SQL Language</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#sgc_standards">Standards Support</a></span>
</dt>
<dt>
<span class="section"><a href="#sgc_data_tables">SQL Data and Tables</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#sgc_temp_tables">Temporary Tables</a></span>
</dt>
<dt>
<span class="section"><a href="#sgc_persist_tables">Persistent Tables</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#sgc_data_type_guide">Short Guide to Data Types</a></span>
</dt>
<dt>
<span class="section"><a href="#sgc_types_ops">Data Types and Operations</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#sgc_numeric_types">Numeric Types</a></span>
</dt>
<dt>
<span class="section"><a href="#sgc_boolean_type">Boolean Type</a></span>
</dt>
<dt>
<span class="section"><a href="#sgc_char_types">Character String Types</a></span>
</dt>
<dt>
<span class="section"><a href="#sgc_binary_types">Binary String Types</a></span>
</dt>
<dt>
<span class="section"><a href="#sgc_bit_types">Bit String Types</a></span>
</dt>
<dt>
<span class="section"><a href="#sgc_lob_data">Lob Data</a></span>
</dt>
<dt>
<span class="section"><a href="#sgc_java_objects">Storage and Handling of Java Objects</a></span>
</dt>
<dt>
<span class="section"><a href="#sgc_length_precision">Type Length, Precision and Scale</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#sgc_datetime_types">Datetime types</a></span>
</dt>
<dt>
<span class="section"><a href="#sgc_interval_typs">Interval Types</a></span>
</dt>
<dt>
<span class="section"><a href="#sgc_array">Arrays</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#sgc_array_def">Array Definition</a></span>
</dt>
<dt>
<span class="section"><a href="#sgc_array_ref">Array Reference</a></span>
</dt>
<dt>
<span class="section"><a href="#sgc_array_ops">Array Operations</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#sgc_index_speed">Indexes and Query Speed</a></span>
</dt>
<dt>
<span class="section"><a href="#sgc_query_opt">Query Processing and Optimisation</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#sgc_indexes_cond">Indexes and Conditions</a></span>
</dt>
<dt>
<span class="section"><a href="#sgc_indexes_ops">Indexes and Operations</a></span>
</dt>
<dt>
<span class="section"><a href="#sgc_indexes_order">Indexes and ORDER BY, OFFSET and LIMIT</a></span>
</dt>
</dl>
</dd>
</dl>
</dd>
<dt>
<span class="chapter"><a href="#sessions-chapt">3. Sessions and Transactions</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#snc_overview">Overview</a></span>
</dt>
<dt>
<span class="section"><a href="#snc_session_attr_vars">Session Attributes and Variables</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#snc_session_attr">Session Attributes</a></span>
</dt>
<dt>
<span class="section"><a href="#snc_session_vars">Session Variables</a></span>
</dt>
<dt>
<span class="section"><a href="#snc_session_tables">Session Tables</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#snc_tx_tx_cc">Transactions and Concurrency Control</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#snc_tx_2pl">Two Phase Locking</a></span>
</dt>
<dt>
<span class="section"><a href="#snc_tx_2pl_si">Two Phase Locking with Snapshot Isolation</a></span>
</dt>
<dt>
<span class="section"><a href="#snc_tx_locks_2pl">Lock Contention in 2PL</a></span>
</dt>
<dt>
<span class="section"><a href="#snc_tx_locks_routines">Locks in SQL Routines and Triggers</a></span>
</dt>
<dt>
<span class="section"><a href="#snc_tx_mvcc">MVCC</a></span>
</dt>
<dt>
<span class="section"><a href="#snc_tx_choosing">Choosing the Transaction Model</a></span>
</dt>
<dt>
<span class="section"><a href="#snc_tx_schema_change">Schema and Database Change</a></span>
</dt>
<dt>
<span class="section"><a href="#snc_tx_access_tables">Simultaneous Access to Tables</a></span>
</dt>
<dt>
<span class="section"><a href="#snc_viewing_sessions">Viewing Sessions</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#snc_statements">Session and Transaction Control Statements</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="chapter"><a href="#databaseobjects-chapt">4. Schemas and Database Objects</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#dbc_overview">Overview</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_schemas_schema_objects">Schemas and Schema Objects</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#dbc_names_references">Names and References</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_character_sets">Character Sets</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_collations">Collations</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_distinct_types">Distinct Types</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_domains_info_schema">Domains</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_number_sequence">Number Sequences</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_tables">Tables</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_views">Views</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_constraints">Constraints</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_assertions">Assertions</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_triggers">Triggers</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_routines">Routines</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_indexes">Indexes</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#dbc_schema_def_statements">Statements for Schema Definition and Manipulation</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#dbc_common_elements">Common Elements and Statements</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_renaming">Renaming Objects</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_commenting">Commenting Objects</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_schema_creation">Schema Creation</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_table_creation">Table Creation</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_table_manupulation">Table Manipulation</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_view_creation">View Creation and Manipulation</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_domain_creation">Domain Creation and Manipulation</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_trigger_creation">Trigger Creation</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_routine_creation">Routine Creation</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_sequence_creation">Sequence Creation</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_procedure_satement">SQL Procedure Statement</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_other_object_creation">Other Schema Object Creation</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#dbc_information_schema">The Information Schema</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#dbc_char_sets_info_schema">Predefined Character Sets, Collations and Domains</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_views_info_schema">Views in INFORMATION SCHEMA</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_visibility_info_schema">Visibility of Information</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_name_info_schema">Name Information</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_data_type_info_schema">Data Type Information</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_product_info_schema">Product Information</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_operations_info_schema">Operations Information</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_standard_views_info_schema">SQL Standard Views</a></span>
</dt>
</dl>
</dd>
</dl>
</dd>
<dt>
<span class="chapter"><a href="#texttables-chapt">5. Text Tables</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#ttc_overview">Overview</a></span>
</dt>
<dt>
<span class="section"><a href="#ttc_implementation">The Implementation</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#ttc_table_definition">Definition of Tables</a></span>
</dt>
<dt>
<span class="section"><a href="#ttc_scope">Scope and Reassignment</a></span>
</dt>
<dt>
<span class="section"><a href="#ttc_nulls">Null Values in Columns of Text Tables</a></span>
</dt>
<dt>
<span class="section"><a href="#ttc_configuration">Configuration</a></span>
</dt>
<dt>
<span class="section"><a href="#ttc_disconnect">Disconnecting Text Tables</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#ttc_issues">Text File Usage</a></span>
</dt>
<dt>
<span class="section"><a href="#ttc_global_props">Text File Global Properties</a></span>
</dt>
<dt>
<span class="section"><a href="#ttc_transactions">Transactions</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="chapter"><a href="#accesscontrol-chapt">6. Access Control</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#acc_overview">Overview</a></span>
</dt>
<dt>
<span class="section"><a href="#acc_auth_and_access_ctrl">Authorizations and Access Control</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#acc_built_in_roles_users">Built-In Roles and Users</a></span>
</dt>
<dt>
<span class="section"><a href="#acc_listing">Listing Users and Roles</a></span>
</dt>
<dt>
<span class="section"><a href="#acc_access_rights">Access Rights</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#acc_statements">Statements for
    Authorization and Access Control</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="chapter"><a href="#dataaccess-chapt">7. Data Access and Change</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#dac_overview">Overview</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_jdbc_cursors_result_sets">Cursors And Result Sets</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#dac_jdbc_columns_rows">Columns and Rows</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_jdbc_cursor_navigation">Navigation</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_jdbc_cursor_updatability">Updatability</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_jdbc_cursor_sensitivity">Sensitivity</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_jdbc_cursor_holdability">Holdability</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_jdbc_autocommit">Autocommit</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_jdbc_overview">JDBC Overview</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_jdbc_parameters">JDBC Parameters</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_jdbc_data_change">JDBC and Data Change Statements</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_jdbc_callable_statement">JDBC Callable Statement</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_jdbc_return_values">JDBC Returned Values</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_declare_cursor">Cursor Declaration</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#dac_syntax_elements">Syntax Elements</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#dac_literals">Literals</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_sql_references">References, etc.</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_value_expression">Value Expression</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_sql_predicates">Predicates</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_aggregate_funcs">Aggregate Functions</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_other_syntax_elements">Other Syntax Elements</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#dac_data_access_statements">Data Access Statements</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#dac_sql_select_statement">Select Statement</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_table">Table</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_subquery">Subquery</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_query_specification">Query Specification</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_table_expression">Table Expression</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_joined_table">Joined Table</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_selection">Selection</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_projection">Projection</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_computed_columns">Computed Columns</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_naming">Naming</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_grouping_operations">Grouping Operations</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_aggregation">Aggregation</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_set_operations">Set Operations</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_with_clause">With Clause and Recursive Queries</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_query_expression">Query Expression</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_ordering">Ordering</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_slicing">Slicing</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#dac_data_change_statements">Data Change Statements</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#dac_delete_statement">Delete Statement</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_truncate_statement">Truncate Statement</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_insert_statement">Insert Statement</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_update_statement">Update Statement</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_merge_statement">Merge Statement</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#dac_diagnostics_state">Diagnostics and State</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="chapter"><a href="#sqlroutines-chapt">8. SQL-Invoked Routines</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#src_routine_definition">Routine Definition</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#src_routine_characteristics">Routine Characteristics</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#src_psm_routines">SQL Language Routines (PSM)</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#src_advantages">Advantages and Disadvantages</a></span>
</dt>
<dt>
<span class="section"><a href="#src_psm_statements">Routine Statements</a></span>
</dt>
<dt>
<span class="section"><a href="#src_psm_compound">Compound Statement</a></span>
</dt>
<dt>
<span class="section"><a href="#src_psm_table_vars">Table Variables</a></span>
</dt>
<dt>
<span class="section"><a href="#src_psm_vars">Variables</a></span>
</dt>
<dt>
<span class="section"><a href="#src_psm_cursors">Cursors</a></span>
</dt>
<dt>
<span class="section"><a href="#src_psm_handlers">Handlers</a></span>
</dt>
<dt>
<span class="section"><a href="#src_psm_assignment">Assignment Statement</a></span>
</dt>
<dt>
<span class="section"><a href="#src_psm_select_single">Select Statement : Single Row</a></span>
</dt>
<dt>
<span class="section"><a href="#src_formal_parameters">Formal Parameters</a></span>
</dt>
<dt>
<span class="section"><a href="#src_psm_iterated_statements">Iterated Statements</a></span>
</dt>
<dt>
<span class="section"><a href="#src_psm_for_statement">Iterated FOR Statement</a></span>
</dt>
<dt>
<span class="section"><a href="#src_psm_conditional">Conditional Statements</a></span>
</dt>
<dt>
<span class="section"><a href="#src_psm_return_statement">Return Statement</a></span>
</dt>
<dt>
<span class="section"><a href="#src_psm_control_statements">Control Statements</a></span>
</dt>
<dt>
<span class="section"><a href="#src_psm_exceptions">Raising Exceptions</a></span>
</dt>
<dt>
<span class="section"><a href="#src_routine_polymorphism">Routine Polymorphism</a></span>
</dt>
<dt>
<span class="section"><a href="#src_returning_data">Returning Data From Procedures</a></span>
</dt>
<dt>
<span class="section"><a href="#src_psm_recursive_routines">Recursive Routines</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#src_jrt_routines">Java Language Routines (SQL/JRT)</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#src_jrt_polymorphis">Polymorphism</a></span>
</dt>
<dt>
<span class="section"><a href="#src_jrt_procedures">Java Language Procedures</a></span>
</dt>
<dt>
<span class="section"><a href="#src_jrt_static_methods">Java Static Methods</a></span>
</dt>
<dt>
<span class="section"><a href="#src_jrt_legacy">Legacy Support</a></span>
</dt>
<dt>
<span class="section"><a href="#src_jrt_access_control">Securing Access to Classes</a></span>
</dt>
<dt>
<span class="section"><a href="#N133A3">Warning</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#src_aggregate_functions">User Defined Aggregate Functions</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#src_aggregate_function_definition">Definition of Aggregate Functions</a></span>
</dt>
<dt>
<span class="section"><a href="#src_psm_aggregate_functions">SQL PSM Aggregate Functions</a></span>
</dt>
<dt>
<span class="section"><a href="#src_jrt_aggregate_functions">Java Aggregate Functions</a></span>
</dt>
</dl>
</dd>
</dl>
</dd>
<dt>
<span class="chapter"><a href="#triggers-chapt">9. Triggers</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#trc_overview">Overview</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#trc_before_triggers">BEFORE Triggers</a></span>
</dt>
<dt>
<span class="section"><a href="#trc_after_triggers">AFTER Triggers</a></span>
</dt>
<dt>
<span class="section"><a href="#trc_instead_of_triggers">INSTEAD OF Triggers</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#trc_trigger_props">Trigger Properties</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#trc_trigger_event">Trigger Event</a></span>
</dt>
<dt>
<span class="section"><a href="#trc_trigger_granularity">Granularity</a></span>
</dt>
<dt>
<span class="section"><a href="#trc_trigger_action_time">Trigger Action Time</a></span>
</dt>
<dt>
<span class="section"><a href="#trc_row_references">References to Rows</a></span>
</dt>
<dt>
<span class="section"><a href="#trc_trigger_condition">Trigger Condition</a></span>
</dt>
<dt>
<span class="section"><a href="#trc_trigger_action_sql">Trigger Action in SQL</a></span>
</dt>
<dt>
<span class="section"><a href="#trc_trigger_action_java">Trigger Action in Java</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#trc_trigger_creation">Trigger Creation</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="chapter"><a href="#builtinfunctions-chapt">10. Built In Functions</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#bfc_overview">Overview</a></span>
</dt>
<dt>
<span class="section"><a href="#bfc_string_binary_functions">String and Binary String Functions</a></span>
</dt>
<dt>
<span class="section"><a href="#bfc_numeric_functions">Numeric Functions</a></span>
</dt>
<dt>
<span class="section"><a href="#bfc_datetime_functions">Date Time and Interval Functions</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#bfc_timezone_functions">Functions to Report the Time Zone.</a></span>
</dt>
<dt>
<span class="section"><a href="#bfc_current_datetime">Functions to Report the Current Datetime</a></span>
</dt>
<dt>
<span class="section"><a href="#bfc_extract_datetime">Functions to Extract an Element of a Datetime</a></span>
</dt>
<dt>
<span class="section"><a href="#bfc_datetime_arithmetic">Functions for Datetime Arithmetic</a></span>
</dt>
<dt>
<span class="section"><a href="#bfc_datetime_format">Functions to Convert or Format a Datetime</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#bfc_array_functions">Array Functions</a></span>
</dt>
<dt>
<span class="section"><a href="#bfc_general_functions">General Functions</a></span>
</dt>
<dt>
<span class="section"><a href="#bfc_system_functions">System Functions</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="chapter"><a href="#management-chapt">11. System Management</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#mtc_modes_tables">Mode of Operation and Tables</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#mtc_modes_operation">Mode of Operation</a></span>
</dt>
<dt>
<span class="section"><a href="#N143CE">Database Types</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_table_types">Tables</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_large_objects">Large Objects</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_deploy_context">Deployment context</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#mtc_acid_persistence">ACID, Persistence and Reliability</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#mtc_acid">Atomicity, Consistency, Isolation, Durability</a></span>
</dt>
<dt>
<span class="section"><a href="#N14491">System Operations</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#mtc_backup">Backing Up Database Catalogs</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#mtc_online_backup">Making Online Backups</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_offline_backup">Making Offline Backups</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_listing_backup">Examining Backups</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_restoring_backup">Restoring a Backup</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#mtc_encrypted_database">Encrypted Databases</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#mtc_encrypted_create">Creating and Accessing an Encrypted Database</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_encrypted_speed">Speed Considerations</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_encrypted_security">Security Considerations</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#mtc_monitoring_operation">Monitoring Database Operations</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#mtc_external_monitoring">External Statement Level Monitoring</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_internal_monitoring">Internal Statement Level Monitoring</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_internal_event_monitoring">Internal Event Monitoring</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_jdc_logging">Log4J and JDK logging</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_server_monitoring">Server Operation Monitoring</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#mtc_database_security">Database Security</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#mtc_security_defaults">Security Defaults</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_authentication_control">Authentication Control</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#mtc_compatibility_other">Compatibility with Other RDBMS</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#mtc_compatibility_postgres">PostgreSQL Compatibility</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_compatibility_mysql">MySQL Compatibility</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_compatibility_firebird">Firebird Compatibility</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_compatibility_derby">Apache Derby Compatibility</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_compatibility_oracle">Oracle Compatibility</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_compatibility_db2">DB2 Compatibility</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_compatibility_mssql">MS SQLServer and Sybase Compatibility</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#mtc_statements">Statements</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#mtc_system_operations">System Operations</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_database_settings">Database Settings</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_sql_settings">SQL Conformance Settings</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_cache_persistence">Cache, Persistence and Files Settings</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_authntication_settings">Authentication Settings</a></span>
</dt>
</dl>
</dd>
</dl>
</dd>
<dt>
<span class="chapter"><a href="#dbproperties-chapt">12. Properties</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#dpc_connection_url">Connection URL</a></span>
</dt>
<dt>
<span class="section"><a href="#dpc_variables_url">Variables In Connection URL</a></span>
</dt>
<dt>
<span class="section"><a href="#dpc_connection_props">Connection properties</a></span>
</dt>
<dt>
<span class="section"><a href="#dpc_db_props_url">Database Properties in Connection URL and Properties</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#dpc_sql_conformance">SQL Conformance Properties</a></span>
</dt>
<dt>
<span class="section"><a href="#dpc_db_operations">Database Operations Properties</a></span>
</dt>
<dt>
<span class="section"><a href="#dpc_db_file_mem">Database File and Memory Properties</a></span>
</dt>
<dt>
<span class="section"><a href="#dpc_crypt_props">Crypt Properties</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#dpc_system_props">System Properties</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="chapter"><a href="#listeners-chapt">13. HyperSQL Network Listeners
    (Servers)</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#lsc_listener_types">Listeners</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#lsc_hsql_server">HyperSQL Server</a></span>
</dt>
<dt>
<span class="section"><a href="#lsc_http_server">HyperSQL HTTP Server</a></span>
</dt>
<dt>
<span class="section"><a href="#lsc_servlet">HyperSQL HTTP Servlet</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#lsc_server_props">Server and Web Server Properties</a></span>
</dt>
<dt>
<span class="section"><a href="#lsc_app_start">Starting a Server from your Application</a></span>
</dt>
<dt>
<span class="section"><a href="#lsc_remote_open">Allowing a Connection to Open or Create a Database</a></span>
</dt>
<dt>
<span class="section"><a href="#lsc_db_props_startup">Specifying Database Properties at Server Start</a></span>
</dt>
<dt>
<span class="section"><a href="#lsc_tls">TLS Encryption</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#lsc_tls_rquirements">Requirements</a></span>
</dt>
<dt>
<span class="section"><a href="#lsc_ssl_connection">Encrypting your JDBC connection</a></span>
</dt>
<dt>
<span class="section"><a href="#lsc_privatekey">Making a Private-key Keystore</a></span>
</dt>
<dt>
<span class="section"><a href="#lsc_auto_server_unix">Automatic Server or WebServer startup on UNIX</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#lsc_acl">Network Access Control</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="chapter"><a href="#unix-chapt">14. HyperSQL on UNIX</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#uxc_purpose">Purpose</a></span>
</dt>
<dt>
<span class="section"><a href="#uxc_install">Installation</a></span>
</dt>
<dt>
<span class="section"><a href="#uxc_cat_setup">Setting up Database Catalog and Listener</a></span>
</dt>
<dt>
<span class="section"><a href="#uxc_access">Accessing your Database</a></span>
</dt>
<dt>
<span class="section"><a href="#uxc_addl_accts">Create additional Accounts</a></span>
</dt>
<dt>
<span class="section"><a href="#uxc_shutdown">Shutdown</a></span>
</dt>
<dt>
<span class="section"><a href="#uxc_daemon">Running Hsqldb as a System Daemon</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#uxc_init_script_portability">Portability of <code class="filename">hsqldb</code> init script</a></span>
</dt>
<dt>
<span class="section"><a href="#uxc_init_script_setup">Init script Setup Procedure</a></span>
</dt>
<dt>
<span class="section"><a href="#uxc_inittrouble">Troubleshooting the Init
      Script</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#uxc_upgrade">Upgrading</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="chapter"><a href="#deployment-chapt">15. Deployment Guide</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#dec_mem_disk_use">Memory and Disk Use</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#dec_table_mem_use">Table Memory Allocation</a></span>
</dt>
<dt>
<span class="section"><a href="#dec_result_mem_use">Result Set Memory Allocation</a></span>
</dt>
<dt>
<span class="section"><a href="#dec_temp_mem_use">Temporary Memory Use During Operations</a></span>
</dt>
<dt>
<span class="section"><a href="#dec_cache_mem_use">Data Cache Memory Allocation</a></span>
</dt>
<dt>
<span class="section"><a href="#dec_pool_mem_use">Object Pool Memory Allocation</a></span>
</dt>
<dt>
<span class="section"><a href="#dec_lob_mem_use">Lob Memory Usage</a></span>
</dt>
<dt>
<span class="section"><a href="#dec_disk_space">Disk Space</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#dec_managing_connections">Managing Database Connections</a></span>
</dt>
<dt>
<span class="section"><a href="#dec_app_dev_testing">Application Development and Testing</a></span>
</dt>
<dt>
<span class="section"><a href="#dec_tweaking">Tweaking the Mode of Operation</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#dec_embedded_desktop_db">Embedded Databases in Desktop Applications</a></span>
</dt>
<dt>
<span class="section"><a href="#dec_embedded_server_db">Embedded Databases in Server Applications</a></span>
</dt>
<dt>
<span class="section"><a href="#dec_mixed_mode_server">Mixed Mode : Embedding a HyperSQL Server (Listener)</a></span>
</dt>
<dt>
<span class="section"><a href="#dec_no_logging">Using HyperSQL Without Logging Data Change</a></span>
</dt>
<dt>
<span class="section"><a href="#dec_bulk_operations">Bulk Inserts, Updates and Deletes</a></span>
</dt>
<dt>
<span class="section"><a href="#dec_nio_access">Using NIO File Access</a></span>
</dt>
<dt>
<span class="section"><a href="#dec_server_db">Server Databases</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#dec_upgrade_database">Upgrading Databases</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#dec_upgrade_via_script">Upgrading From Older
      Versions</a></span>
</dt>
<dt>
<span class="section"><a href="#dec_script_manual_change">Manual Changes to the *.script File</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#dec_backware_compatibility">Backward Compatibility Issues</a></span>
</dt>
<dt>
<span class="section"><a href="#dec_dependency_applications">HyperSQL Dependency Settings for Applications</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#dec_hsqldb_version_pull">What version to Pull</a></span>
</dt>
<dt>
<span class="section"><a href="#dec_snapshot_repos">Using the HyperSQL Snapshot Repository</a></span>
</dt>
<dt>
<span class="section"><a href="#dec_maven_range_version">Range Versioning</a></span>
</dt>
</dl>
</dd>
</dl>
</dd>
<dt>
<span class="appendix"><a href="#lists-app">A. Lists of Keywords</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#lta_standard_keywords">List of SQL Standard Keywords</a></span>
</dt>
<dt>
<span class="section"><a href="#lta_disallowed_keywords">List of SQL Keywords Disallowed as HyperSQL Identifiers</a></span>
</dt>
<dt>
<span class="section"><a href="#lta_function_keywords">Special Function Keywords</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="appendix"><a href="#building-app">B. Building HyperSQL Jars</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#bga_overview">Purpose</a></span>
</dt>
<dt>
<span class="section"><a href="#bga_gradle_invoke">Building with Gradle</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#bga_gradle_gui">Invoking a Gradle Build Graphically</a></span>
</dt>
<dt>
<span class="section"><a href="#bga_gradle_cmd">Invoking a Gradle Build from the Command Line</a></span>
</dt>
<dt>
<span class="section"><a href="#bga_gradle_using">Using Gradle</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#bga_building_ant">Building with Ant</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#bga_ant_obtaining">Obtaining Ant</a></span>
</dt>
<dt>
<span class="section"><a href="#bga_ant_build">Building Hsqldb with Ant</a></span>
</dt>
<dt>
<span class="section"><a href="#bga_old_jdk">Building for Older JDKs</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#bga_build_ide">Building with IDE Compilers</a></span>
</dt>
<dt>
<span class="section"><a href="#bga_codeswitcher">Hsqldb CodeSwitcher</a></span>
</dt>
<dt>
<span class="section"><a href="#bga_build_docs">Building Documentation</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="appendix"><a href="#openoffice-app">C. HyperSQL with OpenOffice</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#ooa_overview">HyperSQL with OpenOffice</a></span>
</dt>
<dt>
<span class="section"><a href="#ooa_database_tool">Using OpenOffice / LibreOffice as a Database Tool</a></span>
</dt>
<dt>
<span class="section"><a href="#ooa_db_files_convert">Converting .odb files to use with HyperSQL Server</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="appendix"><a href="#filelinks-app">D. HyperSQL File Links</a></span>
</dt>
<dt>
<span class="index"><a href="#sql-ind">SQL Index</a></span>
</dt>
<dt>
<span class="index"><a href="#book-ind">General Index</a></span>
</dt>
</dl>
</div>
<div class="list-of-tables">
<p>
<b>List of Tables</b>
</p>
<dl>
<dt>1. <a href="#altformats-tbl">Available formats of this document</a>
</dt>
<dt>10.1. <a href="#N13F81">TO_CHAR, TO_DATE and TO_TIMESTAMP format elements</a>
</dt>
<dt>12.1. <a href="#N14ED2">Memory Database URL</a>
</dt>
<dt>12.2. <a href="#N14F08">File Database URL</a>
</dt>
<dt>12.3. <a href="#N14F3F">Resource Database URL</a>
</dt>
<dt>12.4. <a href="#N14F72">Server Database URL</a>
</dt>
<dt>12.5. <a href="#N15000">User and Password</a>
</dt>
<dt>12.6. <a href="#N15041">Closing old ResultSet when Statement is reused</a>
</dt>
<dt>12.7. <a href="#N15088">Column Names in JDBC ResultSet</a>
</dt>
<dt>12.8. <a href="#N150C1">Creating New Database</a>
</dt>
<dt>12.9. <a href="#N15120">Automatic Shutdown</a>
</dt>
<dt>12.10. <a href="#N1518D">Validity Check Property</a>
</dt>
<dt>12.11. <a href="#N151BE">SQL Keyword Use as Identifier</a>
</dt>
<dt>12.12. <a href="#N151EB">SQL Keyword Starting with the Underscore or Containing Dollar
        Characters</a>
</dt>
<dt>12.13. <a href="#N15218">Reference to Columns Names</a>
</dt>
<dt>12.14. <a href="#N15245">String Size Declaration</a>
</dt>
<dt>12.15. <a href="#N15272">Type Enforcement in Comparison and Assignment</a>
</dt>
<dt>12.16. <a href="#N1529F">Foreign Key Triggered Data Change</a>
</dt>
<dt>12.17. <a href="#N152E2">Use of LOB for LONGVAR Types</a>
</dt>
<dt>12.18. <a href="#N1530F">Concatenation with NULL</a>
</dt>
<dt>12.19. <a href="#N1533C">NULL in Multi-Column UNIQUE Constraints</a>
</dt>
<dt>12.20. <a href="#N15369">Truncation or Rounding in Type Conversion</a>
</dt>
<dt>12.21. <a href="#N15396">Decimal Scale of Division and AVG Values</a>
</dt>
<dt>12.22. <a href="#N153C3">Support for NaN values</a>
</dt>
<dt>12.23. <a href="#N153F0">Sort order of NULL values</a>
</dt>
<dt>12.24. <a href="#N1541D">Sort order of NULL values with DESC</a>
</dt>
<dt>12.25. <a href="#N1544D">String comparison with padding</a>
</dt>
<dt>12.26. <a href="#N1547C">Case Insensitive Varchar columns</a>
</dt>
<dt>12.27. <a href="#N154A9">DB2 Style Syntax</a>
</dt>
<dt>12.28. <a href="#N154D5">MSSQL Style Syntax</a>
</dt>
<dt>12.29. <a href="#N15501">MySQL Style Syntax</a>
</dt>
<dt>12.30. <a href="#N1552E">Oracle Style Syntax</a>
</dt>
<dt>12.31. <a href="#N1555B">PostgreSQL Style Syntax</a>
</dt>
<dt>12.32. <a href="#N1558B">Default Table Type</a>
</dt>
<dt>12.33. <a href="#N155BB">Transaction Control Mode</a>
</dt>
<dt>12.34. <a href="#N155E8">Default Isolation Level for Sessions</a>
</dt>
<dt>12.35. <a href="#N15615">Transaction Rollback in Deadlock</a>
</dt>
<dt>12.36. <a href="#N15642">Time Zone and Interval Types</a>
</dt>
<dt>12.37. <a href="#N15679">Opening Database as Read Only</a>
</dt>
<dt>12.38. <a href="#N156A9">Opening Database Without Modifying the Files</a>
</dt>
<dt>12.39. <a href="#N156D9">Huge database files and tables</a>
</dt>
<dt>12.40. <a href="#N15709">Event Logging</a>
</dt>
<dt>12.41. <a href="#N15739">SQL Logging</a>
</dt>
<dt>12.42. <a href="#N15769">Temporary Result Rows in Memory</a>
</dt>
<dt>12.43. <a href="#N15796">Rows Cached In Memory</a>
</dt>
<dt>12.44. <a href="#N157C8">Rows Cached In Memory</a>
</dt>
<dt>12.45. <a href="#N157F7">Size of Rows Cached in Memory</a>
</dt>
<dt>12.46. <a href="#N15826">Size Scale of Disk Table Storage</a>
</dt>
<dt>12.47. <a href="#N15853">Size Scale of LOB Storage</a>
</dt>
<dt>12.48. <a href="#N15880">Compression of BLOB and CLOB data</a>
</dt>
<dt>12.49. <a href="#N158AD">Internal Backup of Database Files</a>
</dt>
<dt>12.50. <a href="#N158DC">Use of Lock File</a>
</dt>
<dt>12.51. <a href="#N1590C">Logging Data Change Statements</a>
</dt>
<dt>12.52. <a href="#N15942">Automatic Checkpoint Frequency</a>
</dt>
<dt>12.53. <a href="#N15978">Automatic Defrag at Checkpoint</a>
</dt>
<dt>12.54. <a href="#N159A5">Compression of the .script file</a>
</dt>
<dt>12.55. <a href="#N159D5">Logging Data Change Statements Frequency</a>
</dt>
<dt>12.56. <a href="#N15A02">Logging Data Change Statements Frequency</a>
</dt>
<dt>12.57. <a href="#N15A2F">Use of NIO for Disk Table Storage</a>
</dt>
<dt>12.58. <a href="#N15A5F">Use of NIO for Disk Table Storage</a>
</dt>
<dt>12.59. <a href="#N15A8C">Recovery Log Processing</a>
</dt>
<dt>12.60. <a href="#N15AB9">Default Properties for TEXT Tables</a>
</dt>
<dt>12.61. <a href="#N15AED">Forcing Garbage Collection</a>
</dt>
<dt>12.62. <a href="#N15B1E">Crypt Property For LOBs</a>
</dt>
<dt>12.63. <a href="#N15B4B">Cipher Key for Encrypted Database</a>
</dt>
<dt>12.64. <a href="#N15B78">Crypt Provider Encrypted Database</a>
</dt>
<dt>12.65. <a href="#N15BA5">Cipher Specification for Encrypted Database</a>
</dt>
<dt>12.66. <a href="#N15BDF">Logging Framework</a>
</dt>
<dt>12.67. <a href="#N15C09">Text Tables</a>
</dt>
<dt>12.68. <a href="#N15C33">Java Functions</a>
</dt>
<dt>13.1. <a href="#N15CF3">common server and webserver properties</a>
</dt>
<dt>13.2. <a href="#N15D90">server properties</a>
</dt>
<dt>13.3. <a href="#N15DC2">webserver properties</a>
</dt>
</dl>
</div>
<div class="list-of-examples">
<p>
<b>List of Examples</b>
</p>
<dl>
<dt>1.1. <a href="#N1022F">Java code to connect to the local hsql Server</a>
</dt>
<dt>1.2. <a href="#N10239">Java code to connect to the local http Server</a>
</dt>
<dt>1.3. <a href="#N1025D">Java code to connect to the local secure SSL hsql and http
          Servers</a>
</dt>
<dt>1.4. <a href="#N10303">specifying a connection property to shutdown the database when
        the last connection is closed</a>
</dt>
<dt>1.5. <a href="#N10320">specifying a connection property to disallow creating a new
        database</a>
</dt>
<dt>3.1. <a href="#N10980">User-defined Session Variables</a>
</dt>
<dt>3.2. <a href="#N10995">User-defined Temporary Session Tables</a>
</dt>
<dt>3.3. <a href="#N10AA0">Setting Transaction Characteristics</a>
</dt>
<dt>3.4. <a href="#N10ACE">Locking Tables</a>
</dt>
<dt>3.5. <a href="#N10B31">Rollback</a>
</dt>
<dt>3.6. <a href="#N10B63">Setting Session Characteristics</a>
</dt>
<dt>3.7. <a href="#N10B79">Setting Session Authorization</a>
</dt>
<dt>3.8. <a href="#N10BA6">Setting Session Time Zone</a>
</dt>
<dt>4.1. <a href="#N10D36">inserting the next sequence value into a table row</a>
</dt>
<dt>4.2. <a href="#N10D3D">numbering returned rows of a SELECT in sequential order</a>
</dt>
<dt>4.3. <a href="#N10D49">using the last value of a sequence</a>
</dt>
<dt>4.4. <a href="#N10DE7">Column values which satisfy a 2-column UNIQUE
        constraint</a>
</dt>
<dt>11.1. <a href="#N14451">Using CACHED tables for the LOB schema</a>
</dt>
<dt>11.2. <a href="#N14518">Offline Backup Example</a>
</dt>
<dt>11.3. <a href="#N14539">Listing a Backup with DbBackup</a>
</dt>
<dt>11.4. <a href="#N14550">Restoring a Backup with DbBackup</a>
</dt>
<dt>11.5. <a href="#N148EC">SQL Log Example</a>
</dt>
<dt>11.6. <a href="#N14CAF">Finding foreign key rows with no parents after a bulk
        import</a>
</dt>
<dt>13.1. <a href="#N15ED4">Exporting certificate from the server's keystore</a>
</dt>
<dt>13.2. <a href="#N15EE6">Adding a certificate to the client keystore</a>
</dt>
<dt>13.3. <a href="#N15EFA">Specifying your own trust store to a JDBC client</a>
</dt>
<dt>13.4. <a href="#N15F75">Getting a pem-style private key into a JKS keystore</a>
</dt>
<dt>13.5. <a href="#N15FFE">Validating and Testing an ACL file</a>
</dt>
<dt>14.1. <a href="#N162C6">example sqltool.rc stanza</a>
</dt>
<dt>15.1. <a href="#N16428">Using CACHED tables for the LOB schema</a>
</dt>
<dt>15.2. <a href="#N164B6">MainInvoker Example</a>
</dt>
<dt>15.3. <a href="#N16664">HyperSQL Snapshot Repository Definition</a>
</dt>
<dt>15.4. <a href="#N1666D">Sample Snapshot Ivy Dependency</a>
</dt>
<dt>15.5. <a href="#N16672">Sample Snapshot Maven Dependency</a>
</dt>
<dt>15.6. <a href="#N16677">Sample Snapshot Gradle Dependency</a>
</dt>
<dt>15.7. <a href="#N1668F">Sample Snapshot ivy.xml loaded by Ivyxml plugin</a>
</dt>
<dt>15.8. <a href="#N16694">Sample Snapshot Groovy Dependency, using Grape</a>
</dt>
<dt>15.9. <a href="#N166C0">Sample Range Ivy Dependency</a>
</dt>
<dt>15.10. <a href="#N166D0">Sample Range Maven Dependency</a>
</dt>
<dt>15.11. <a href="#N166DB">Sample Range Gradle Dependency</a>
</dt>
<dt>15.12. <a href="#N166F3">Sample Range ivy.xml loaded by Ivyxml plugin</a>
</dt>
<dt>15.13. <a href="#N166F8">Sample Range Groovy Dependency, using Grape</a>
</dt>
<dt>B.1. <a href="#N16A2D">Buiding the standard Hsqldb jar file with Ant</a>
</dt>
<dt>B.2. <a href="#N16A4D">Example source code before CodeSwitcher is run</a>
</dt>
<dt>B.3. <a href="#N16A54">CodeSwitcher command line invocation</a>
</dt>
<dt>B.4. <a href="#N16A5E">Source code after CodeSwitcher processing</a>
</dt>
</dl>
</div>
<div class="preface" title="Preface">
<div class="titlepage">
<div>
<div>
<h2 class="title">
<a name="book-pref"></a>Preface</h2>
</div>
</div>
</div>
<div class="toc">
<p>
<b>Table of Contents</b>
</p>
<dl>
<dt>
<span class="section"><a href="#altformats-sect">Available formats for this document</a></span>
</dt>
</dl>
</div>
<p>HSQLDB (HyperSQL DataBase) is a modern relational database manager
    that conforms closely to the SQL:2008 Standard and JDBC 4 specifications.
    It supports all core features and many of the optional features of
    SQL:2008.</p>
<p>The first versions of HSQLDB were released in 2001. Version 2, first
    released in 2010, includes a complete rewrite of most parts of the
    database engine.</p>
<p>This documentation covers the latest HyperSQL version 2.3. This
    documentation is regularly improved and updated. The latest, updated
    version can be found at http://hsqldb.org/doc/2.0/</p>
<p>If you notice any mistakes in this document, or if you have problems
    with the procedures themselves, please use the HSQLDB support facilities
    which are listed at http://hsqldb.org/support</p>
<div class="section" title="Available formats for this document">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="altformats-sect"></a>Available formats for this document</h2>
</div>
</div>
</div>
<p>This document is available in several formats.</p>
<p>
      You may be reading this document right now at http://hsqldb.org/doc/2.0, or in
      a distribution somewhere else.
      I hereby call the document distribution from which you are reading 
      this, your <span class="emphasis"><em>current distro</em></span>.
  </p>
<p>
      http://hsqldb.org/doc/2.0 hosts the latest production versions of all available formats.
      If you want a different format of the same <span class="emphasis"><em>version</em></span>
      of the document you are reading now, then you should try your
      current distro.
      If you want the latest production version, you should try http://hsqldb.org/doc/2.0.
  </p>
<p>
      Sometimes, distributions other than http://hsqldb.org/doc/2.0 do not host all
      available formats.
      So, if you can't access the format that you want in your current
      distro, you have no choice but to use the newest production version at 
      http://hsqldb.org/doc/2.0.
  </p>
<p>
    
</p>
<div class="table">
<a name="altformats-tbl"></a>
<p class="title">
<b>Table&nbsp;1.&nbsp;Available formats of this document</b>
</p>
<div class="table-contents">
<table summary="Available formats of this document" cellspacing="0" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="3cm" align="left">
<col width="4cm" align="left">
<col align="left">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">format</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">your distro</th><th style="border-bottom: 0.5pt solid ; " align="left">at http://hsqldb.org/doc/2.0</th>
</tr>
</thead>
<tbody>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">
              Chunked HTML
          </td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">
              <a class="link" href="index.html" target="_top">index.html</a>
          </td><td style="border-bottom: 0.5pt solid ; " align="left">
          <a class="link" href="http://hsqldb.org/doc/2.0/guide/" target="_top">http://hsqldb.org/doc/2.0/guide/</a>
          </td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">
              All-in-one HTML
          </td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">
              <a class="link" href="guide.html" target="_top">guide.html</a>
          </td><td style="border-bottom: 0.5pt solid ; " align="left">
        <a class="link" href="http://hsqldb.org/doc/2.0/guide/guide.html" target="_top">http://hsqldb.org/doc/2.0/guide/guide.html</a>
          </td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; " align="left">
              PDF
          </td><td style="border-right: 0.5pt solid ; " align="left">
              <a class="link" href="guide.pdf" target="_top">guide.pdf</a>
          </td><td style="" align="left">
          <a class="link" href="http://hsqldb.org/doc/2.0/guide/guide.pdf" target="_top">http://hsqldb.org/doc/2.0/guide/guide.pdf</a>
          </td>
</tr>
</tbody>
</table>
</div>
</div>
<p>
<br class="table-break">
    If you are reading this document now with a standalone PDF reader, the
    <span class="guilabel">your distro</span> links may not work.
  </p>
</div>
</div>
<div class="chapter" title="Chapter&nbsp;1.&nbsp;Running and Using HyperSQL">
<div class="titlepage">
<div>
<div>
<h2 class="title">
<a name="running-chapt"></a>Chapter&nbsp;1.&nbsp;Running and Using HyperSQL</h2>
</div>
<div>
<div class="authorgroup">
<div class="author">
<h3 class="author">
<span class="firstname">Fred</span> <span class="surname">Toussi</span>
</h3>
<div class="affiliation">
<span class="orgname">The HSQL Development Group<br>
</span>
</div>
</div>
</div>
</div>
<div>
<p class="releaseinfo">$Revision: 5240 $</p>
</div>
<div>
<div class="legalnotice" title="Legal Notice">
<a name="N100CC"></a>
<p>Copyright 2002-2013 Fred Toussi. Permission is granted to
      distribute this document without any alteration under the terms of the
      HSQLDB license. Additional permission is granted to the HSQL Development
      Group to distribute this document with or without alterations under the
      terms of the HSQLDB license.</p>
</div>
</div>
<div>
<p class="pubdate">2014-02-13 18:21:41-0500</p>
</div>
</div>
</div>
<div class="toc">
<p>
<b>Table of Contents</b>
</p>
<dl>
<dt>
<span class="section"><a href="#N100CF">Introduction</a></span>
</dt>
<dt>
<span class="section"><a href="#rgc_hsqldb_jar">The HSQLDB Jar</a></span>
</dt>
<dt>
<span class="section"><a href="#rgc_access_tools">Running Database Access Tools</a></span>
</dt>
<dt>
<span class="section"><a href="#rgc_hsqldb_db">A HyperSQL Database</a></span>
</dt>
<dt>
<span class="section"><a href="#rgc_inprocess">In-Process Access to Database Catalogs</a></span>
</dt>
<dt>
<span class="section"><a href="#rgc_server_modes">Server Modes</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#rgc_hsql_server">HyperSQL HSQL Server</a></span>
</dt>
<dt>
<span class="section"><a href="#rgc_http_server">HyperSQL HTTP Server</a></span>
</dt>
<dt>
<span class="section"><a href="#rgc_http_servlet">HyperSQL HTTP Servlet</a></span>
</dt>
<dt>
<span class="section"><a href="#rgc_connecting_db">Connecting to a Database Server</a></span>
</dt>
<dt>
<span class="section"><a href="#rgc_security">Security Considerations</a></span>
</dt>
<dt>
<span class="section"><a href="#rgc_multiple_db">Using Multiple Databases</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#rgc-data-access">Accessing the Data</a></span>
</dt>
<dt>
<span class="section"><a href="#rgc_closing_db">Closing the Database</a></span>
</dt>
<dt>
<span class="section"><a href="#rgc_new_db">Creating a New Database</a></span>
</dt>
</dl>
</div>
<div class="section" title="Introduction">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="N100CF"></a>Introduction</h2>
</div>
</div>
</div>
<p>HyperSQL Database (HSQLDB ) is a modern relational database system.
    Version 2.3 is the latest release of the all-new version 2 code. Written
    from ground up to follow the international ISO SQL:2011 standard, it
    supports the complete set of the classic features, together with optional
    features such as stored procedures and triggers.</p>
<p>HyperSQL is used for development, testing and deployment of database
    applications.</p>
<p>Standard compliance is the most unique characteristic of HyperSQL.
    There are several other distinctive features. HyperSQL can provide
    database access within the user's application process, within an
    application server, or as a separate server process. HyperSQL can run
    entirely in memory using dedicated fast memory structures as opposed to
    ram disk. HyperSQL can use disk persistence in a flexible way, with
    reliable crash-recovery. HyperSQL is the only open-source relational
    database management system with a high performance dedicated lob storage
    system, suitable for gigabytes of lob data. It is also the only relational
    database that can create and access large comma delimited files as SQL
    tables. HyperSQL supports three live switchable transaction control
    models, including fully multi threaded MVCC, and is suitable for high
    performance transaction processing applications. HyperSQL is also suitable
    for business intelligence, ETL and other applications that process large
    data sets. HyperSQL has a wide range of enterprise deployment options,
    such as XA transactions, connection pooling data sources and remote
    authentication.</p>
<p>New SQL syntax compatibility modes have been added to HyperSQL.
    These modes allow a high degree of compatibility with several other
    database systems which use non-standard SQL syntax.</p>
<p>HyperSQL is written in the Java programming language and runs in a
    Java virtual machine (JVM). It supports the JDBC interface for database
    access.</p>
<p>An ODBC driver is also available as a separate download.</p>
<p>This guide covers the database engine features, SQL syntax and
    different modes of operation. The Server, JDBC interfaces, pooling and XA
    components are documented in the JavaDoc. Utilities such as SqlTool and
    DatabaseManager are covered in a separate Utilities Guide.</p>
</div>
<div class="section" title="The HSQLDB Jar">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="rgc_hsqldb_jar"></a>The HSQLDB Jar</h2>
</div>
</div>
</div>
<p>The HSQLDB jar package, hsqldb.jar, is located in the /lib directory
    of the ZIP package and contains several components and programs.</p>
<div class="itemizedlist" title="Components of the Hsqldb jar package">
<p class="title">
<b>Components of the Hsqldb jar package</b>
</p>
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>HyperSQL RDBMS Engine (HSQLDB)</p>
</li>
<li class="listitem">
<p>HyperSQL JDBC Driver</p>
</li>
<li class="listitem">
<p>Database Manager (GUI database access tool, with Swing and AWT
        versions)</p>
</li>
</ul>
</div>
<p>The HyperSQL RDBMS and JDBC Driver provide the core functionality.
    DatabaseManagers are general-purpose database access tools that can be
    used with any database engine that has a JDBC driver.</p>
<p>An additional jar, sqltool.jar, contains Sql Tool, command line
    database access tool. This is a general purpose command line database
    access tool that can be ued with other database engines as well.</p>
</div>
<div class="section" title="Running Database Access Tools">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="rgc_access_tools"></a>Running Database Access Tools</h2>
</div>
</div>
</div>
<p>The tools are used for interactive user access to databases,
    including creation of a database, inserting or modifying data, or querying
    the database. All tools are run in the normal way for Java programs. In
    the following example the Swing version of the Database Manager is
    executed. The <code class="filename">hsqldb.jar</code> is located in the directory
    <code class="filename">../lib</code> relative to the current directory.</p>
<pre class="screen"> java -cp ../lib/hsqldb.jar org.hsqldb.util.DatabaseManagerSwing</pre>
<p>If <code class="filename">hsqldb.jar</code> is in the current directory, the
    command would change to:</p>
<pre class="screen"> java -cp hsqldb.jar org.hsqldb.util.DatabaseManagerSwing</pre>
<div class="itemizedlist" title="Main classes for the Hsqldb tools">
<p class="title">
<b>Main classes for the Hsqldb tools</b>
</p>
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>
<code class="classname">org.hsqldb.util.DatabaseManager</code>
</p>
</li>
<li class="listitem">
<p>
<code class="classname">org.hsqldb.util.DatabaseManagerSwing</code>
</p>
</li>
</ul>
</div>
<p>When a tool is up and running, you can connect to a database (may be
    a new database) and use SQL commands to access and modify the data.</p>
<p>Tools can use command line arguments. You can add the command line
    argument --help to get a list of available arguments for these
    tools.</p>
<p>Double clicking the HSQLDB jar will start the DatabaseManagerSwing
    application.</p>
</div>
<div class="section" title="A HyperSQL Database">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="rgc_hsqldb_db"></a>A HyperSQL Database</h2>
</div>
</div>
</div>
<p>Each HyperSQL database is called a catalog. There are three types of
    catalog depending on how the data is stored.</p>
<div class="itemizedlist" title="Types of catalog data">
<p class="title">
<b>Types of catalog data</b>
</p>
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>
<em class="glossterm">mem:</em> stored entirely in RAM - without any
        persistence beyond the JVM process's life</p>
</li>
<li class="listitem">
<p>
<em class="glossterm">file:</em> stored in filesystem files</p>
</li>
<li class="listitem">
<p>
<em class="glossterm">res:</em> stored in a Java resource, such as a
        Jar and always read-only</p>
</li>
</ul>
</div>
<p>All-in-memory, <em class="glossterm">mem:</em> catalogs can be used for
    test data or as sophisticated caches for an application. These databases
    do not have any files.</p>
<p>A <em class="glossterm">file</em>: catalog consists of between 2 to 6
    files, all named the same but with different extensions, located in the
    same directory. For example, the database named "test" consists of the
    following files:</p>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>
<code class="filename">test.properties</code>
</p>
</li>
<li class="listitem">
<p>
<code class="filename">test.script</code>
</p>
</li>
<li class="listitem">
<p>
<code class="filename">test.log</code>
</p>
</li>
<li class="listitem">
<p>
<code class="filename">test.data</code>
</p>
</li>
<li class="listitem">
<p>
<code class="filename">test.backup</code>
</p>
</li>
<li class="listitem">
<p>
<code class="filename">test.lobs</code>
</p>
</li>
</ul>
</div>
<p>The properties file contains a few settings about the database. The
    script file contains the definition of tables and other database objects,
    plus the data for non-cached tables. The log file contains recent changes
    to the database. The data file contains the data for cached tables and the
    backup file is a compressed backup of the last known consistent state of
    the data file. All these files are essential and should never be deleted.
    For some catalogs, the <code class="filename">test.data</code> and
    <code class="filename">test.backup</code> files will not be present. In addition to
    those files, a HyperSQL database may link to any formatted text files,
    such as CSV lists, anywhere on the disk.</p>
<p>While the "test" catalog is open, a <code class="filename">test.log</code>
    file is used to write the changes made to data. This file is removed at a
    normal SHUTDOWN. Otherwise (with abnormal shutdown) this file is used at
    the next startup to redo the changes. A <code class="filename">test.lck </code>file
    is also used to record the fact that the database is open. This is deleted
    at a normal SHUTDOWN.</p>
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
<table border="0" summary="Note">
<tr>
<td valign="top" align="center" rowspan="2" width="25"><img alt="[Note]" src="../images/db/note.png"></td><th align="left">Note</th>
</tr>
<tr>
<td valign="top" align="left">
<p>When the engine closes the database at a shutdown, it creates
      temporary files with the extension <code class="literal">.new</code> which it then
      renames to those listed above. These files should not be deleted by the
      user. At the time of the next startup, all such files will be renamed or
      deleted by the database engine. In some circumstances, a
      <code class="filename">test.data.xxx.old</code> is created and deleted afterwards
      by the database engine. The user can delete these
      <code class="filename">test.data.xxx.old</code> files.</p>
</td>
</tr>
</table>
</div>
<p>A <em class="glossterm">res:</em> catalog consists of the files for a
    small, read-only database that can be stored inside a Java resource such
    as a ZIP or JAR archive and distributed as part of a Java application
    program.</p>
</div>
<div class="section" title="In-Process Access to Database Catalogs">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="rgc_inprocess"></a>In-Process Access to Database Catalogs</h2>
</div>
</div>
</div>
<p>In general, JDBC is used for all access to databases. This is done
    by making a connection to the database, then using various methods of the
    <code class="classname">java.sql.Connection</code> object that is returned to
    access the data. Access to an <em class="glossterm">in-process</em> database
    is started from JDBC, with the database path specified in the connection
    URL. For example, if the <em class="glossterm">file: </em>database name is
    "testdb" and its files are located in the same directory as where the
    command to run your application was issued, the following code is used for
    the connection:</p>
<pre class="programlisting"> Connection c = DriverManager.getConnection("jdbc:hsqldb:file:testdb", "SA", "");</pre>
<p>The database file path format can be specified using forward slashes
    in Windows hosts as well as Linux hosts. So relative paths or paths that
    refer to the same directory on the same drive can be identical. For
    example if your database directory in Linux is <code class="filename">/opt/db/
    containing a database testdb (with files named testdb.*), then the
    database file path is /opt/db/testdb.</code> If you create an
    identical directory structure on the <code class="literal">C:</code> drive of a
    Windows host, you can use the same URL in both Windows and Linux:</p>
<pre class="programlisting"> Connection c = DriverManager.getConnection("jdbc:hsqldb:file:/opt/db/testdb", "SA", "");</pre>
<p>When using relative paths, these paths will be taken relative to the
    directory in which the shell command to start the Java Virtual Machine was
    executed. Refer to the Javadoc for <code class="classname"><a class="classname" href="#JDBCConnection.html-link">JDBCConnection</a></code> for more
    details.</p>
<p>Paths and database names for file databases are treated as
    case-sensitive when the database is created or the first connection is
    made to the database. But if a second connection is made to an open
    database, using a path and name that differs only in case, then the
    connection is made to the existing open database. This measure is
    necessary because in Windows the two paths are equivalent.</p>
<p>A <em class="glossterm">mem:</em> database is specified by the
    <em class="glossterm">mem:</em> protocol. For <em class="glossterm">mem:</em>
    databases, the path is simply a name. Several <em class="glossterm">mem:</em>
    databases can exist at the same time and distinguished by their names. In
    the example below, the database is called "mymemdb":</p>
<pre class="programlisting"> Connection c = DriverManager.getConnection("jdbc:hsqldb:mem:mymemdb", "SA", "");</pre>
<p>A <em class="glossterm">res:</em> database, is specified by the
    <em class="glossterm">res:</em> protocol. As it is a Java resource, the
    database path is a Java URL (similar to the path to a class). In the
    example below, "resdb" is the root name of the database files, which
    exists in the directory "org/my/path" within the classpath (probably in a
    Jar). A Java resource is stored in a compressed format and is decompressed
    in memory when it is used. For this reason, a <em class="glossterm">res:</em>
    database should not contain large amounts of data and is always
    read-only.</p>
<pre class="programlisting"> Connection c = DriverManager.getConnection("jdbc:hsqldb:res:org.my.path.resdb", "SA", "");</pre>
<p>The first time <em class="glossterm">in-process</em> connection is made
    to a database, some general data structures are initialised and a few
    helper threads are started. After this, creation of connections and calls
    to JDBC methods of the connections execute as if they are part of the Java
    application that is making the calls. When the SQL command "SHUTDOWN" is
    executed, the global structures and helper threads for the database are
    destroyed.</p>
<p>Note that only one Java process at a time can make
    <em class="glossterm">in-process</em> connections to a given
    <em class="glossterm">file:</em> database. However, if the
    <em class="glossterm">file:</em> database has been made read-only, or if
    connections are made to a <em class="glossterm">res:</em> database, then it is
    possible to make <em class="glossterm">in-process</em> connections from
    multiple Java processes.</p>
</div>
<div class="section" title="Server Modes">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="rgc_server_modes"></a>Server Modes</h2>
</div>
</div>
</div>
<p>For most applications, <em class="glossterm">in-process</em> access is
    faster, as the data is not converted and sent over the network. The main
    drawback is that it is not possible by default to connect to the database
    from outside your application. As a result you cannot check the contents
    of the database with external tools such as Database Manager while your
    application is running.</p>
<p>Server modes provide the maximum accessibility. The database engine
    runs in a JVM and opens one or more <em class="glossterm">in-process</em>
    catalogs. It listens for connections from programs on the same computer or
    other computers on the network. It translates these connections into
    <em class="glossterm">in-process</em> connections to the databases.</p>
<p>Several different programs can connect to the server and retrieve or
    update information. Applications programs (clients) connect to the server
    using the HyperSQL JDBC driver. In most server modes, the server can serve
    an unlimited number of databases that are specified at the time of running
    the server, or optionally, as a connection request is received.</p>
<p>A Sever mode is also the preferred mode of running the database
    during development. It allows you to query the database from a separate
    database access utility while your application is running.</p>
<p>There are three server modes, based on the protocol used for
    communications between the client and server. They are briefly discussed
    below. More details on servers is provided in the <a class="link" href="#listeners-chapt" title="Chapter&nbsp;13.&nbsp;HyperSQL Network Listeners (Servers)">HyperSQL Network Listeners
    (Servers)</a> chapter.</p>
<div class="section" title="HyperSQL HSQL Server">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="rgc_hsql_server"></a>HyperSQL HSQL Server</h3>
</div>
</div>
</div>
<p>This is the preferred way of running a database server and the
      fastest one. A proprietary communications protocol is used for this
      mode. A command similar to those used for running tools and described
      above is used for running the server. The following example of the
      command for starting the server starts the server with one (default)
      database with files named "mydb.*" and the public name of "xdb". The
      public name hides the file names from users.</p>
<div class="informalexample">
<pre class="screen"> java -cp ../lib/hsqldb.jar org.hsqldb.server.Server --database.0 file:mydb --dbname.0 xdb</pre>
</div>
<p>The command line argument <code class="literal">--help</code> can be used to
      get a list of available arguments.</p>
</div>
<div class="section" title="HyperSQL HTTP Server">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="rgc_http_server"></a>HyperSQL HTTP Server</h3>
</div>
</div>
</div>
<p>This method of access is used when the computer hosting the
      database server is restricted to the HTTP protocol. The only reason for
      using this method of access is restrictions imposed by firewalls on the
      client or server machines and it should not be used where there are no
      such restrictions. The HyperSQL HTTP Server is a special web server that
      allows JDBC clients to connect via HTTP. The server can also act as a
      small general-purpose web server for static pages.</p>
<p>To run an HTTP server, replace the main class for the server in
      the example command line above with the following:</p>
<div class="informalexample">
<pre class="screen"> org.hsqldb.server.WebServer</pre>
</div>
<p>The command line argument <code class="literal">--help</code> can be used to
      get a list of available arguments.</p>
</div>
<div class="section" title="HyperSQL HTTP Servlet">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="rgc_http_servlet"></a>HyperSQL HTTP Servlet</h3>
</div>
</div>
</div>
<p>This method of access also uses the HTTP protocol. It is used when
      a separate servlet engine (or application server) such as Tomcat or
      Resin provides access to the database. The Servlet Mode cannot be
      started independently from the servlet engine. The
      <code class="filename">Servlet</code> class, in the HSQLDB jar, should be
      installed on the application server to provide the connection. The
      database file path is specified using an application server property.
      Refer to the source file <code class="filename"><a class="filename" href="#Servlet.java-link">
      src/org/hsqldb/server/Servlet.java</a></code> to see the details.</p>
<p>Both HTTP Server and Servlet modes can be accessed using the JDBC
      driver at the client end. They do not provide a web front end to the
      database. The Servlet mode can serve multiple databases.</p>
<p>Please note that you do not normally use this mode if you are
      using the database engine in an application server. In this situation,
      connections to a catalog are usually made
      <em class="glossterm">in-process</em>, or using a separate Server</p>
</div>
<div class="section" title="Connecting to a Database Server">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="rgc_connecting_db"></a>Connecting to a Database Server</h3>
</div>
</div>
</div>
<p>When a HyperSQL server is running, client programs can connect to
      it using the HSQLDB JDBC Driver contained in
      <code class="filename">hsqldb.jar</code>. Full information on how to connect to a
      server is provided in the Java Documentation for <code class="classname"><a class="classname" href="#JDBCConnection.html-link"> JDBCConnection</a></code>
      (located in the <code class="filename">/doc/apidocs</code> directory of HSQLDB
      distribution). A common example is connection to the default port (9001)
      used for the <em class="glossterm">hsql:</em> protocol on the same
      machine:</p>
<div class="example">
<a name="N1022F"></a>
<p class="title">
<b>Example&nbsp;1.1.&nbsp;Java code to connect to the local hsql Server</b>
</p>
<div class="example-contents">
<pre class="programlisting"> try {
     Class.forName("org.hsqldb.jdbc.JDBCDriver" );
 } catch (Exception e) {
     System.err.println("ERROR: failed to load HSQLDB JDBC driver.");
     e.printStackTrace();
     return;
 }

 Connection c = DriverManager.getConnection("jdbc:hsqldb:hsql://localhost/xdb", "SA", "");</pre>
</div>
</div>
<br class="example-break">
<p>If the HyperSQL HTTP server is used, the protocol is
      <em class="glossterm">http:</em> and the URL will be different:</p>
<div class="example">
<a name="N10239"></a>
<p class="title">
<b>Example&nbsp;1.2.&nbsp;Java code to connect to the local http Server</b>
</p>
<div class="example-contents">
<pre class="programlisting"> Connection c = DriverManager.getConnection("jdbc:hsqldb:http://localhost/xdb", "SA", "");</pre>
</div>
</div>
<br class="example-break">
<p>Note in the above connection URL, there is no mention of the
      database file, as this was specified when running the server. Instead,
      the public name defined for dbname.0 is used. Also, see the <a class="link" href="#listeners-chapt" title="Chapter&nbsp;13.&nbsp;HyperSQL Network Listeners (Servers)">HyperSQL Network Listeners
    (Servers)</a> chapter
      for the connection URL when there is more than one database per server
      instance.</p>
</div>
<div class="section" title="Security Considerations">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="rgc_security"></a>Security Considerations</h3>
</div>
</div>
</div>
<a name="N10248" class="indexterm"></a>
<p>When a HyperSQL server is run, network access should be adequately
      protected. Source IP addresses may be restricted by use of our <a class="link" href="#lsc_acl" title="Network Access Control">Access Control List feature</a>, network
      filtering software, firewall software, or standalone firewalls. Only
      secure passwords should be used-- most importantly, the password for the
      default system user should be changed from the default empty string. If
      you are purposefully providing data to the public, then the wide-open
      public network connection should be used exclusively to access the
      public data via read-only accounts. (i.e., neither secure data nor
      privileged accounts should use this connection). These considerations
      also apply to HyperSQL servers run with the HTTP protocol.</p>
<p>HyperSQL provides two optional security mechanisms. The <a class="link" href="#lsc_tls" title="TLS Encryption">encrypted SSL protocol</a>, and <a class="link" href="#lsc_acl" title="Network Access Control">Access Control Lists</a>. Both mechanisms can
      be specified when running the Server or WebServer. On the client, the
      URL to connect to an SSL server is slightly different:</p>
<div class="example">
<a name="N1025D"></a>
<p class="title">
<b>Example&nbsp;1.3.&nbsp;Java code to connect to the local secure SSL hsql and http
          Servers</b>
</p>
<div class="example-contents">
<pre class="programlisting"> Connection c = DriverManager.getConnection("jdbc:hsqldb:hsqls://localhost/xdb", "SA", "");
 Connection c = DriverManager.getConnection("jdbc:hsqldb:https://localhost/xdb", "SA", "");
</pre>
</div>
</div>
<p>
<br class="example-break">The security features are discussed in detail in the <a class="link" href="#listeners-chapt" title="Chapter&nbsp;13.&nbsp;HyperSQL Network Listeners (Servers)">HyperSQL Network Listeners
    (Servers)</a>
      chapter.</p>
</div>
<div class="section" title="Using Multiple Databases">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="rgc_multiple_db"></a>Using Multiple Databases</h3>
</div>
</div>
</div>
<p>A server can provide connections to more than one database. In the
      examples above, more than one set of database names can be specified on
      the command line. It is also possible to specify all the databases in a
      <code class="literal">.properties</code> file, instead of the command line. These
      capabilities are covered in the <a class="link" href="#listeners-chapt" title="Chapter&nbsp;13.&nbsp;HyperSQL Network Listeners (Servers)">HyperSQL Network Listeners
    (Servers)</a> chapter</p>
</div>
</div>
<div class="section" title="Accessing the Data">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="rgc-data-access"></a>Accessing the Data</h2>
</div>
</div>
</div>
<p>As shown so far, a <code class="classname">java.sql.Connection</code> object
    is always used to access the database. But the speed and performance
    depends on the type of connection.</p>
<p>Establishing a connection and closing it has some overheads,
    therefore it is not good practice to create a new connection to perform a
    small number of operations. A connection should be reused as much as
    possible and closed only when it is not going to be used again for a long
    while.</p>
<p>Reuse is more important for server connections. A server connection
    uses a TCP port for communications. Each time a connection is made, a port
    is allocated by the operating system and deallocated after the connection
    is closed. If many connections are made from a single client, the
    operating system may not be able to keep up and may refuse the connection
    attempt.</p>
<p>A <code class="classname">java.sql.Connection</code> object has some methods
    that return further <code class="classname">java.sql.*</code> objects. All these
    objects belong to the connection that returned them and are closed when
    the connection is closed. These objects can be reused, but if they are not
    needed after performing the operations, they should be closed.</p>
<p>A <code class="classname">java.sql.DatabaseMetaData</code> object is used to
    get metadata for the database.</p>
<p>A <code class="classname">java.sql.Statement</code> object is used to
    execute queries and data change statements. A
    <code class="classname">java.sql.Statement</code> can be reused to execute a
    different statement each time.</p>
<p>A <code class="classname">java.sql.PreparedStatement</code> object is used
    to execute a single statement repeatedly. The SQL statement usually
    contains parameters, which can be set to new values before each reuse.
    When a <code class="classname">java.sql.PreparedStatement</code> object is
    created, the engine keeps the compiled SQL statement for reuse, until the
    <code class="classname">java.sql.PreparedStatement</code> object is closed. As a
    result, repeated use of a
    <code class="classname">java.sql.PreparedStatement</code> is much faster than
    using a <code class="classname">java.sql.Statement</code> object.</p>
<p>A <code class="classname">java.sql.CallableStatement</code> object is used
    to execute an SQL CALL statement. The SQL CALL statement may contain
    parameters, which should be set to new values before each reuse. Similar
    to <code class="classname">java.sql.PreparedStatement</code>, the engine keeps the
    compiled SQL statement for reuse, until the
    <code class="classname">java.sql.CallableStatement</code> object is closed.</p>
<p>A <code class="classname">java.sql.Connection</code> object also has some
    methods for transaction control.</p>
<p>The <code class="methodname">commit()</code> method performs a
    <code class="literal">COMMIT</code> while the <code class="methodname">rollback()</code>
    method performs a <code class="literal">ROLLBACK</code> SQL statement.</p>
<p>The <code class="methodname">setSavepoint(String name)</code> method
    performs a <code class="literal">SAVEPOINT &lt;name&gt;</code> SQL statement and
    returns a <code class="classname">java.sql.Savepoint</code> object. The
    <code class="methodname">rollback(Savepoint name)</code> method performs a
    <code class="literal">ROLLBACK TO SAVEPOINT &lt;name&gt;</code> SQL
    statement.</p>
<p>The Javadoc for <code class="classname"><a class="classname" href="#JDBCConnection.html-link">
    JDBCConnection</a></code>, <code class="classname"><a class="classname" href="#JDBCDriver.html-link">
    JDBCDriver</a></code>, <code class="classname"><a class="classname" href="#JDBCDatabaseMetaData.html-link">
    JDBCDatabaseMetadata</a></code> <code class="classname"><a class="classname" href="#JDBCResultSet.html-link"> JDBCResultSet</a></code>,
    <code class="classname"><a class="classname" href="#JDBCStatement.html-link">
    JDBCStatement</a></code>, <code class="classname"><a class="classname" href="#JDBCPreparedStatement.html-link">
    JDBCPreparedStatement</a></code> list all the supported JDBC methods
    together with information that is specific to HSQLDB.</p>
</div>
<div class="section" title="Closing the Database">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="rgc_closing_db"></a>Closing the Database</h2>
</div>
</div>
</div>
<p>All databases running in different modes can be closed with the
    SHUTDOWN command, issued as an SQL statement.</p>
<p>When SHUTDOWN is issued, all active transactions are rolled back.
    The catalog files are then saved in a form that can be opened quickly the
    next time the catalog is opened.</p>
<p>A special form of closing the database is via the SHUTDOWN COMPACT
    command. This command rewrites the <code class="literal">.data</code> file that
    contains the information stored in CACHED tables and compacts it to its
    minimum size. This command should be issued periodically, especially when
    lots of inserts, updates or deletes have been performed on the cached
    tables. Changes to the structure of the database, such as dropping or
    modifying populated CACHED tables or indexes also create large amounts of
    unused file space that can be reclaimed using this command.</p>
<p>Databases are not closed when the last connection to the database is
    explicitly closed via JDBC. A connection property,
    <code class="literal">shutdown=true</code>, can be specified on the first connection
    to the database (the connection that opens the database) to force a
    shutdown when the last connection closes.</p>
<div class="example">
<a name="N10303"></a>
<p class="title">
<b>Example&nbsp;1.4.&nbsp;specifying a connection property to shutdown the database when
        the last connection is closed</b>
</p>
<div class="example-contents">
<pre class="programlisting"> Connection c = DriverManager.getConnection(
         "jdbc:hsqldb:file:/opt/db/testdb;shutdown=true", "SA", "");</pre>
</div>
</div>
<p>
<br class="example-break">This feature is useful for running tests, where it may not be
    practical to shutdown the database after each test. But it is not
    recommended for application programs.</p>
</div>
<div class="section" title="Creating a New Database">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="rgc_new_db"></a>Creating a New Database</h2>
</div>
</div>
</div>
<p>When a server instance is started, or when a connection is made to
    an <em class="glossterm">in-process</em> database, a new, empty database is
    created if no database exists at the given path.</p>
<p>With HyperSQL 2.0 the username and password that are specified for
    the connection are used for the new database. Both the username and
    password are case-sensitive. (The exception is the default SA user, which
    is not case-sensitive). If no username or password is specified, the
    default SA user and an empty password are used.</p>
<p>This feature has a side effect that can confuse new users. If a
    mistake is made in specifying the path for connecting to an existing
    database, a connection is nevertheless established to a new database. For
    troubleshooting purposes, you can specify a connection property
    <span class="property">ifexists</span>=<code class="literal">true</code> to allow connection
    to an existing database only and avoid creating a new database. In this
    case, if the database does not exist, the
    <code class="methodname">getConnection()</code> method will throw an
    exception.</p>
<div class="example">
<a name="N10320"></a>
<p class="title">
<b>Example&nbsp;1.5.&nbsp;specifying a connection property to disallow creating a new
        database</b>
</p>
<div class="example-contents">
<pre class="programlisting"> Connection c = DriverManager.getConnection(
         "jdbc:hsqldb:file:/opt/db/testdb;ifexists=true", "SA", "");</pre>
</div>
</div>
<p>
<br class="example-break">
</p>
<p>A database has many optional properties, described in the <a class="link" href="#management-chapt" title="Chapter&nbsp;11.&nbsp;System Management">System Management</a> chapter. You can specify most of
    these properties on the URL or in the connection properties for the first
    connection that creates the database. See the <a class="link" href="#dbproperties-chapt" title="Chapter&nbsp;12.&nbsp;Properties">Properties</a> chapter.</p>
</div>
</div>
<div class="chapter" title="Chapter&nbsp;2.&nbsp;SQL Language">
<div class="titlepage">
<div>
<div>
<h2 class="title">
<a name="sqlgeneral-chapt"></a>Chapter&nbsp;2.&nbsp;SQL Language</h2>
</div>
<div>
<div class="authorgroup">
<div class="author">
<h3 class="author">
<span class="firstname">Fred</span> <span class="surname">Toussi</span>
</h3>
<div class="affiliation">
<span class="orgname">The HSQL Development Group<br>
</span>
</div>
</div>
</div>
</div>
<div>
<p class="releaseinfo">$Revision: 5287 $</p>
</div>
<div>
<div class="legalnotice" title="Legal Notice">
<a name="N10357"></a>
<p>Copyright 2002-2012 Fred Toussi. Permission is granted to
      distribute this document without any alteration under the terms of the
      HSQLDB license. Additional permission is granted to the HSQL Development
      Group to distribute this document with or without alterations under the
      terms of the HSQLDB license.</p>
</div>
</div>
<div>
<p class="pubdate">2014-02-13 18:21:41-0500</p>
</div>
</div>
</div>
<div class="toc">
<p>
<b>Table of Contents</b>
</p>
<dl>
<dt>
<span class="section"><a href="#sgc_standards">Standards Support</a></span>
</dt>
<dt>
<span class="section"><a href="#sgc_data_tables">SQL Data and Tables</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#sgc_temp_tables">Temporary Tables</a></span>
</dt>
<dt>
<span class="section"><a href="#sgc_persist_tables">Persistent Tables</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#sgc_data_type_guide">Short Guide to Data Types</a></span>
</dt>
<dt>
<span class="section"><a href="#sgc_types_ops">Data Types and Operations</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#sgc_numeric_types">Numeric Types</a></span>
</dt>
<dt>
<span class="section"><a href="#sgc_boolean_type">Boolean Type</a></span>
</dt>
<dt>
<span class="section"><a href="#sgc_char_types">Character String Types</a></span>
</dt>
<dt>
<span class="section"><a href="#sgc_binary_types">Binary String Types</a></span>
</dt>
<dt>
<span class="section"><a href="#sgc_bit_types">Bit String Types</a></span>
</dt>
<dt>
<span class="section"><a href="#sgc_lob_data">Lob Data</a></span>
</dt>
<dt>
<span class="section"><a href="#sgc_java_objects">Storage and Handling of Java Objects</a></span>
</dt>
<dt>
<span class="section"><a href="#sgc_length_precision">Type Length, Precision and Scale</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#sgc_datetime_types">Datetime types</a></span>
</dt>
<dt>
<span class="section"><a href="#sgc_interval_typs">Interval Types</a></span>
</dt>
<dt>
<span class="section"><a href="#sgc_array">Arrays</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#sgc_array_def">Array Definition</a></span>
</dt>
<dt>
<span class="section"><a href="#sgc_array_ref">Array Reference</a></span>
</dt>
<dt>
<span class="section"><a href="#sgc_array_ops">Array Operations</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#sgc_index_speed">Indexes and Query Speed</a></span>
</dt>
<dt>
<span class="section"><a href="#sgc_query_opt">Query Processing and Optimisation</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#sgc_indexes_cond">Indexes and Conditions</a></span>
</dt>
<dt>
<span class="section"><a href="#sgc_indexes_ops">Indexes and Operations</a></span>
</dt>
<dt>
<span class="section"><a href="#sgc_indexes_order">Indexes and ORDER BY, OFFSET and LIMIT</a></span>
</dt>
</dl>
</dd>
</dl>
</div>
<div class="section" title="Standards Support">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="sgc_standards"></a>Standards Support</h2>
</div>
</div>
</div>
<p>HyperSQL 2 supports the dialect of SQL defined by SQL standards 92,
    1999, 2003, 2008 and 2011. This means where a feature of the standard is
    supported, e.g. left outer join, the syntax is that specified by the
    standard text. Almost all syntactic features of SQL-92 up to Advanced
    Level are supported, as well as SQL:2011 core and many optional features
    of this standard. Work is in progress for a formal declaration of
    conformance.</p>
<p>At the time of this release, HyperSQL supports the widest range of
    SQL standard features among all open source RDBMS.</p>
<p>Various chapters of this guide list the supported syntax. When
    writing or converting existing SQL DDL (Data Definition Language), DML
    (Data Manipulation Language) or DQL (Data Query Language) statements for
    HSQLDB, you should consult the supported syntax and modify the statements
    accordingly. Some statements written for older versions may have to be
    modified.</p>
<p>Over 300 words are reserved by the standard and should not be used
    as table or column names. For example, the word POSITION is reserved as it
    is a function defined by the Standards with a similar role as
    <code class="methodname">String.indexOf()</code> in Java. HyperSQL does not
    currently prevent you from using a reserved word if it does not support
    its use or can distinguish it. For example CUBE is a reserved words that
    is not currently supported by HyperSQL and is allowed as a table or column
    name. You should avoid using such names as future versions of HyperSQL are
    likely to support the reserved words and may reject your table definitions
    or queries. The full list of SQL reserved words is in the appendix <a class="link" href="#lists-app" title="Appendix&nbsp;A.&nbsp;Lists of Keywords">Lists of Keywords</a> .</p>
<p>There are several user-defined properties to control the strict
    application of the SQL Standard in different areas.</p>
<p>If you have to use a reserved keyword as the name of a database
    object, you can enclose it in double quotes.</p>
<p>HyperSQL also supports enhancements with keywords and expressions
    that are not part of the SQL standard. Expressions such as <code class="literal">SELECT
    TOP 5 FROM ..</code>, <code class="literal">SELECT LIMIT 0 10 FROM ...</code> or
    <code class="literal">DROP TABLE mytable IF EXISTS</code> are among such
    constructs.</p>
<p>Many print books cover SQL Standard syntax and can be
    consulted.</p>
<p>In HyperSQL version 2, all features of JDBC4 that apply to the
    capabilities of HSQLDB are fully supported. The relevant JDBC classes are
    thoroughly documented with additional clarifications and HyperSQL specific
    comments. See the <a class="link" href="#javadoc-link">JavaDoc</a> for the
    <code class="classname">org.hsqldb.jdbc.*</code> classes.</p>
</div>
<div class="section" title="SQL Data and Tables">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="sgc_data_tables"></a>SQL Data and Tables</h2>
</div>
</div>
</div>
<p>In an SQL system, all significant data is stored in tables and
    sequence generators. Therefore, the first step in creating a database is
    defining the tables and their columns. The SQL standard supports temporary
    tables, which are for temporary data, and permanent base tables, which are
    for persistent data.</p>
<div class="section" title="Temporary Tables">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="sgc_temp_tables"></a>Temporary Tables</h3>
</div>
</div>
</div>
<p>Data in TEMPORARY tables is not saved and lasts only for the
      lifetime of the session. The contents of each TEMP table is visible only
      from the session that is used to populate it.</p>
<p>HyperSQL supports two types of temporary tables.</p>
<p>The <code class="literal">GLOBAL TEMPORARY</code> type is a schema object.
      It is created with the <code class="literal">CREATE GLOBAL TEMPORARY TABLE</code>
      statement. The definition of the table persists, and each session has
      access to the table. But each session sees its own copy of the table,
      which is empty at the beginning of the session.</p>
<p>The <code class="literal">LOCAL TEMPORARY</code> type is not a schema
      object. It is created with the <code class="literal">DECLARE LOCAL TEMPORARY
      TABLE</code> statement. The table definition lasts only for the
      duration of the session and is not persisted in the database. The table
      can be declared in the middle of a transaction without committing the
      transaction. If a schema name is needed to reference these tables in a
      given SQL statement, the pseudo schema names <code class="literal">MODULE</code>
      or <code class="literal">SESSION</code> can be used.</p>
<p>When the session commits, the contents of all temporary tables are
      cleared by default. If the table definition statements includes ON
      COMMIT PRESERVE ROWS, then the contents are kept when a commit takes
      place.</p>
<p>The rows in temporary tables are stored in memory by default. If
      the <code class="literal">hsqldb.result_max_memory_rows</code> property has been
      set or the <code class="literal">SET SESSION RESULT MEMORY ROWS &lt;row
      count&gt;</code> has been specified, tables with row count above the
      setting are stored on disk.</p>
</div>
<div class="section" title="Persistent Tables">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="sgc_persist_tables"></a>Persistent Tables</h3>
</div>
</div>
</div>
<p>HyperSQL supports the Standard definition of persistent base
      table, but defines three types according to the way the data is stored.
      These are MEMORY tables, CACHED tables and TEXT tables.</p>
<p>Memory tables are the default type when the CREATE TABLE command
      is used. Their data is held entirely in memory but any change to their
      structure or contents is written to the <code class="filename">*.log</code> and
      <code class="filename">*.script</code> files. The <code class="filename">*.script</code>
      file and the <code class="filename">*.log</code> file are read the next time the
      database is opened, and the MEMORY tables are recreated with all their
      contents. So unlike TEMPORARY tables, MEMORY tables are persistent. When
      the database is opened, all the data for the memory tables is read and
      inserted. This process may take a long time if the database is larger
      than tens of megabytes. When the database is shutdown, all the data is
      saved. This can also take a long time.</p>
<p>CACHED tables are created with the CREATE CACHED TABLE command.
      Only part of their data or indexes is held in memory, allowing large
      tables that would otherwise take up to several hundred megabytes of
      memory. Another advantage of cached tables is that the database engine
      takes less time to start up when a cached table is used for large
      amounts of data. The disadvantage of cached tables is a reduction in
      speed. Do not use cached tables if your data set is relatively small. In
      an application with some small tables and some large ones, it is better
      to use the default, MEMORY mode for the small tables.</p>
<p>TEXT tables use a CSV (Comma Separated Value) or other delimited
      text file as the source of their data. You can specify an existing CSV
      file, such as a dump from another database or program, as the source of
      a TEXT table. Alternatively, you can specify an empty file to be filled
      with data by the database engine. TEXT tables are efficient in memory
      usage as they cache only part of the text data and all of the indexes.
      The Text table data source can always be reassigned to a different file
      if necessary. The commands are needed to set up a TEXT table as detailed
      in the <a class="link" href="#texttables-chapt" title="Chapter&nbsp;5.&nbsp;Text Tables">Text Tables</a> chapter.</p>
<p>With all-in-memory databases, both MEMORY table and CACHED table
      declarations are treated as declarations for non-persistent memory
      tables. In the latest versions of HyperSQL, TEXT table declarations are
      allowed in all-in-memory databases.</p>
<p>The default type of tables resulting from future CREATE TABLE
      statements can be specified with the SQL command:</p>
<pre class="programlisting"> SET DATABASE DEFAULT TABLE TYPE { CACHED | MEMORY };</pre>
<p>The
      type of an existing table can be changed with the SQL command:</p>
<pre class="programlisting"> SET TABLE &lt;table name&gt; TYPE { CACHED | MEMORY };</pre>
<p>SQL
      statements access different types of tables uniformly. No change to
      statements is needed to access different types of table.</p>
</div>
</div>
<div class="section" title="Short Guide to Data Types">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="sgc_data_type_guide"></a>Short Guide to Data Types</h2>
</div>
</div>
</div>
<p>Most other RDBMS do not conform to the SQL Standard in all areas,
    but they are gradually moving towards Standard conformance. When switching
    from another SQL dialect, the following should be considered:</p>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>Numeric types TINYINT, SMALLINT, INTEGER and BIGINT are types
        with fixed binary precision. These types are more efficient to store
        and retrieve. NUMERIC and DECIMAL are types with user-defined decimal
        precision. They can be used with zero scale to store very large
        integers, or with a non-zero scale to store decimal fractions. The
        DOUBLE type is a 64 bit, approximate floating point types. HyperSQL
        even allows you to store infinity in this type.</p>
</li>
<li class="listitem">
<p>The BOOLEAN type is for logical values and can hold TRUE, FALSE
        or UNKNOWN. Although HyperSQL allows you to use one and zero in
        assignment or comparison, you should use the standard values for this
        type.</p>
</li>
<li class="listitem">
<p>Character string types are CHAR(L), VARCHAR(L) and CLOB. CHAR is
        for fixed width strings and any string that is assigned to this type
        is padded with spaces at the end. Do not use this type for general
        storage of strings. If you use CHAR without the length L, then it is
        interpreted as a single character string. Use VARCHAR(L) for general
        strings. There are only memory limits and performance implications for
        the maximum length of VARCHAR(L). If the strings are larger than a few
        kilobytes, consider using CLOB. The CLOB types is for very large
        strings. Do not use this type for short strings as there are
        performance implications. The CLOB type is a better choice for the
        storage of long strings. By default LONGVARCHAR is a synonym for a
        long VARCHAR and can be used without specifying the size. You can set
        LONGVARCHAR to map to CLOB, with the
        <code class="literal">sql.longvar_is_lob</code> connection property or the SET
        DATABASE SQL LONGVAR IS LOB TRUE statement.</p>
</li>
<li class="listitem">
<p>Binary string types are BINARY(L), VARBINARY(L) and BLOB. Do not
        use BINARY(L) unless you are storing keys such as UUID. This type pads
        short binary strings with zero bytes. BINARY without the length L
        means a single byte. Use VARBINARY(L) for general binary strings, and
        BLOB for large binary objects. You should apply the same
        considerations as with the character string types. By default
        LONGVARBINARY is a synonym for a long VARCHAR and can be used without
        specifying the size. You can set LONGVARBINARY to map to BLOB, with
        the <code class="literal">sql.longvar_is_lob</code> connection property or the
        SET DATABASE SQL LONGVAR IS LOB TRUE statement.</p>
</li>
<li class="listitem">
<p>The BIT(L) and BITVARYING(L) types are for bit maps. Do not use
        them for other types of data. BIT without the length L argument means
        a single bit and is sometimes used as a logical type. Use BOOLEAN
        instead of this type.</p>
</li>
<li class="listitem">
<p>The datetime types DATE, TIME and TIMESTAMP, together with their
        WITH TIME ZONE variations are available. Read the details in this
        chapter on how to use these types.</p>
</li>
<li class="listitem">
<p>The INTERVAL type is very powerful when used together with the
        datetime types. This is very easy to use, but is supported mainly by
        "big iron" database systems. Note that functions that add days or
        months to datetime values are not really a substitute for the INTERVAL
        type. Expressions such as <code class="literal">(datecol - 7 DAY) &gt;
        CURRENT_DATE</code> are optimised to use indexes when it is
        possible, while the equivalent function calls are not
        optimised.</p>
</li>
<li class="listitem">
<p>The OTHER type is for storage of Java objects. If your objects
        are large, serialize them in your application and store them as BLOB
        in the database.</p>
</li>
<li class="listitem">
<p>The ARRAY type supports all base types except LOB and OTHER
        types. ARRAY data objects are held in memory while being processed. It
        is therefore not recommended to store more than about a thousand
        objects in an ARRAY in normal operations with disk based databases.
        For specialised applications, use ARRAY with as many elements as your
        memory allocation can support.</p>
</li>
</ul>
</div>
<p>HyperSQL 2.3 has several compatibility modes which allow the type
    names that are used by other RDBMS to be accepted and translated into the
    closest SQL Standard type. For example the type TEXT, supported by MySQL
    and PostgreSQL is translated in these compatibility modes.</p>
</div>
<div class="section" title="Data Types and Operations">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="sgc_types_ops"></a>Data Types and Operations</h2>
</div>
</div>
</div>
<p>HyperSQL supports all the types defined by SQL-92, plus BOOLEAN,
    BINARY and LOB types that were later added to the SQL Standard. It also
    supports the non-standard OTHER type to store serializable Java
    objects.</p>
<p>SQL is a strongly typed language. All data stored in specific
    columns of tables and other objects (such as sequence generators) have
    specific types. Each data item conforms to the type limits such as
    precision and scale for the column. It also conforms to any additional
    integrity constraints that are defined as CHECK constraints in domains or
    tables. Types can be explicitly converted using the CAST expression, but
    in most expressions they are converted automatically.</p>
<p>Data is returned to the user (or the application program) as a
    result of executing SQL statements such as query expressions or function
    calls. All statements are compiled prior to execution and the return type
    of the data is known after compilation and before execution. Therefore,
    once a statement is prepared, the data type of each column of the returned
    result is known, including any precision or scale property. The type does
    not change when the same query that returned one row, returns many rows as
    a result of adding more data to the tables.</p>
<p>Some SQL functions used within SQL statements are polymorphic, but
    the exact type of the argument and the return value is determined at
    compile time.</p>
<p>When a statement is prepared, using a JDBC PreparedStatement object,
    it is compiled by the engine and the type of the columns of its ResultSet
    and / or its parameters are accessible through the methods of
    PreparedStatement.</p>
<div class="section" title="Numeric Types">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="sgc_numeric_types"></a>Numeric Types</h3>
</div>
</div>
</div>
<a name="N1041C" class="indexterm"></a>
<p>TINYINT, SMALLINT, INTEGER, BIGINT, NUMERIC and DECIMAL (without a
      decimal point) are the supported integral types. They correspond
      respectively to <code class="classname">byte</code>,
      <code class="classname">short</code>, <code class="classname">int</code>,
      <code class="classname">long</code>, <code class="classname">BigDecimal</code> and
      <code class="classname">BigDecimal</code> Java types in the range of values that
      they can represent (NUMERIC and DECIMAL are equivalent). The type
      TINYINT is an HSQLDB extension to the SQL Standard, while the others
      conform to the Standard definition. The SQL type dictates the maximum
      and minimum values that can be held in a field of each type. For example
      the value range for TINYINT is -128 to +127. The bit precision of
      TINYINT, SMALLINT, INTEGER and BIGINT is respectively 8, 16, 32 and 64.
      For NUMERIC and DECIMAL, decimal precision is used.</p>
<p>DECIMAL and NUMERIC with decimal fractions are mapped to
      <code class="classname">java.math.BigDecimal</code> and can have very large
      numbers of digits. In HyperSQL the two types are equivalent. These
      types, together with integral types, are called exact numeric
      types.</p>
<p>In HyperSQL, REAL, FLOAT, DOUBLE are equivalent and all mapped to
      <code class="classname">double</code> in Java. These types are defined by the
      SQL Standard as approximate numeric types. The bit-precision of all
      these types is 64 bits.</p>
<p>The decimal precision and scale of NUMERIC and DECIMAL types can
      be optionally defined. For example, DECIMAL(10,2) means maximum total
      number of digits is 10 and there are always 2 digits after the decimal
      point, while DECIMAL(10) means 10 digits without a decimal point. The
      bit-precision of FLOAT can be defined but it is ignored and the default
      bit-precision of 64 is used. The default precision of NUMERIC and
      DECIMAL (when not defined) is 100.</p>
<p>Note: If a database has been set to ignore type precision limits
      with the SET DATABASE SQL SIZE FALSE command, then a type definition of
      DECIMAL with no precision and scale is treated as DECIMAL(100,10). In
      normal operation, it is treated as DECIMAL(100).</p>
<p>
<span class="bold"><strong>Integral Types</strong></span>
</p>
<p>In expressions, TINYINT, SMALLINT, INTEGER, BIGINT, NUMERIC and
      DECIMAL (without a decimal point) can be freely combined and no data
      narrowing takes place. The resulting value is of a type that can support
      all possible values.</p>
<p>If the SELECT statement refers to a simple column or function,
      then the return type is the type corresponding to the column or the
      return type of the function. For example:</p>
<div class="informalexample">
<pre class="programlisting"> CREATE TABLE t(a INTEGER, b BIGINT);
 SELECT MAX(a), MAX(b) FROM t;</pre>
</div>
<p>will return a <code class="classname">ResultSet</code> where the type of
      the first column is <code class="classname">java.lang.Integer</code> and the
      second column is <code class="classname">java.lang.Long</code>. However,</p>
<div class="informalexample">
<pre class="programlisting"> SELECT MAX(a) + 1, MAX(b) + 1 FROM t;</pre>
</div>
<p>will return <code class="classname">java.lang.Long</code> and
      <code class="classname">BigDecimal</code> values, generated as a result of
      uniform type promotion for all the return values. Note that type
      promotion to <code class="classname">BigDecimal</code> ensures the correct value
      is returned if <code class="literal">MAX(b)</code> evaluates to
      <code class="literal">Long.MAX_VALUE</code>.</p>
<p>There is no built-in limit on the size of intermediate integral
      values in expressions. As a result, you should check for the type of the
      <code class="classname">ResultSet</code> column and choose an appropriate
      <code class="methodname">getXXXX()</code> method to retrieve it. Alternatively,
      you can use the <code class="methodname">getObject()</code> method, then cast
      the result to <code class="classname">java.lang.Number</code> and use the
      <code class="methodname">intValue()</code> or
      <code class="methodname">longValue()</code> methods on the result.</p>
<p>When the result of an expression is stored in a column of a
      database table, it has to fit in the target column, otherwise an error
      is returned. For example when <code class="literal">1234567890123456789012 /
      12345687901234567890</code> is evaluated, the result can be stored in
      any integral type column, even a TINYINT column, as it is a small
      value.</p>
<p>In SQL Statements, an integer literal is treated as INTEGER,
      unless its value does not fit. In this case it is treated as BIGINT or
      DECIMAL, depending on the value.</p>
<p>Depending on the types of the operands, the result of the
      operation is returned in a JDBC <code class="classname">ResultSet</code> in any
      of the related Java types: <code class="classname">Integer</code>,
      <code class="classname">Long</code> or <code class="classname">BigDecimal</code>. The
      <code class="methodname">ResultSet.getXXXX()</code> methods can be used to
      retrieve the values so long as the returned value can be represented by
      the resulting type. This type is deterministically based on the query,
      not on the actual rows returned.</p>
<p>
<span class="bold"><strong>Other Numeric Types</strong></span>
</p>
<p>In SQL statements, number literals with a decimal point are
      treated as DECIMAL unless they are written with an exponent. Thus
      <code class="literal">0.2</code> is considered a DECIMAL value but
      <code class="literal">0.2E0</code> is considered a DOUBLE value.</p>
<p>When an approximate numeric type, REAL, FLOAT or DOUBLE (all
      synonymous) is part of an expression involving different numeric types,
      the type of the result is DOUBLE. DECIMAL values can be converted to
      DOUBLE unless they are beyond the <code class="literal">Double.MIN_VALUE -
      Double.MAX_VALUE</code> range. For example, A * B, A / B, A + B, etc.
      will return a DOUBLE value if either A or B is a DOUBLE.</p>
<p>Otherwise, when no DOUBLE value exists, if a DECIMAL or NUMERIC
      value is part an expression, the type of the result is DECIMAL or
      NUMERIC. Similar to integral values, when the result of an expression is
      assigned to a table column, the value has to fit in the target column,
      otherwise an error is returned. This means a small, 4 digit value of
      DECIMAL type can be assigned to a column of SMALLINT or INTEGER, but a
      value with 15 digits cannot.</p>
<p>When a DECIMAL value is multiplied by a DECIMAL or integral type,
      the resulting scale is the sum of the scales of the two terms. When they
      are divided, the result is a value with a scale (number of digits to the
      right of the decimal point) equal to the larger of the scales of the two
      terms. The precision for both operations is calculated (usually
      increased) to allow all possible results.</p>
<p>The distinction between DOUBLE and DECIMAL is important when a
      division takes place. For example, <code class="literal">10.0/8.0</code> (DECIMAL)
      equals <code class="literal">1.2</code> but <code class="literal">10.0E0/8.0E0</code>
      (DOUBLE) equals <code class="literal">1.25</code>. Without division operations,
      DECIMAL values represent exact arithmetic.</p>
<p>REAL, FLOAT and DOUBLE values are all stored in the database as
      <code class="classname">java.lang.Double</code> objects. Special values such as
      NaN and +-Infinity are also stored and supported. These values can be
      submitted to the database via JDBC
      <code class="classname">PreparedStatement</code> methods and are returned in
      <code class="classname">ResultSet</code> objects. In order to allow division by
      zero of DOUBLE values in SQL statements (which returns NaN or
      +-Infinity) you should set the property hsqldb.double_nan as false (SET
      DATABASE SQL DOUBLE NAN FALSE). The double values can be retrieved from
      a <code class="classname">ResultSet</code> in the required type so long as they
      can be represented. For setting the values, when
      <code class="methodname">PreparedStatement.setDouble()</code> or
      <code class="methodname">setFloat()</code> is used, the value is treated as a
      DOUBLE automatically.</p>
<p>In short,</p>
<p>
<code class="literal">&lt;numeric type&gt; ::= &lt;exact numeric type&gt; |
      &lt;approximate numeric type&gt;</code>
</p>
<p>
<code class="literal">&lt;exact numeric type&gt; ::= NUMERIC [ &lt;left
      paren&gt; &lt;precision&gt; [ &lt;comma&gt; &lt;scale&gt; ] &lt;right
      paren&gt; ] | { DECIMAL | DEC } [ &lt;left paren&gt; &lt;precision&gt; [
      &lt;comma&gt; &lt;scale&gt; ] &lt;right paren&gt; ] | SMALLINT | INTEGER
      | INT | BIGINT</code>
</p>
<p>
<code class="literal">&lt;approximate numeric type&gt; ::= FLOAT [ &lt;left
      paren&gt; &lt;precision&gt; &lt;right paren&gt; ] | REAL | DOUBLE
      PRECISION</code>
</p>
<p>
<code class="literal">&lt;precision&gt; ::= &lt;unsigned
      integer&gt;</code>
</p>
<p>
<code class="literal">&lt;scale&gt; ::= &lt;unsigned
      integer&gt;</code>
</p>
</div>
<div class="section" title="Boolean Type">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="sgc_boolean_type"></a>Boolean Type</h3>
</div>
</div>
</div>
<a name="N104E5" class="indexterm"></a>
<p>The BOOLEAN type conforms to the SQL Standard and represents the
      values <code class="literal">TRUE</code>, <code class="literal">FALSE</code> and
      <code class="literal">UNKNOWN</code>. This type of column can be initialised with
      Java boolean values, or with <code class="literal">NULL</code> for the
      <code class="literal">UNKNOWN</code> value.</p>
<p>The three-value logic is sometimes misunderstood. For example, x
      IN (1, 2, NULL) does not return true if x is NULL.</p>
<p>In previous versions of HyperSQL, BIT was simply an alias for
      BOOLEAN. In version 2, BIT is a single-bit bit map.</p>
<p>
<code class="literal">&lt;boolean type&gt; ::= BOOLEAN</code>
</p>
<p>The SQL Standard does not support type conversion to BOOLEAN apart
      from character strings that consists of boolean literals. Because the
      BOOLEAN type is relatively new to the Standard, several database
      products used other types to represent boolean values. For improved
      compatibility, HyperSQL allows some type conversions to boolean.</p>
<p>Values of BIT and BIT VARYING types with length 1 can be converted
      to BOOLEAN. If the bit is set, the result of conversion is the TRUE
      value, otherwise it is FALSE.</p>
<p>Values of TINYINT, SMALLINT, INTEGER and BIGINT types can be
      converted to BOOLEAN. If the value is zero, the result is the FALSE
      value, otherwise it is TRUE.</p>
</div>
<div class="section" title="Character String Types">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="sgc_char_types"></a>Character String Types</h3>
</div>
</div>
</div>
<a name="N1050C" class="indexterm"></a>
<p>The CHARACTER, CHARACTER VARYING and CLOB types are the SQL
      Standard character string types. CHAR, VARCHAR and CHARACTER LARGE
      OBJECT are synonyms for these types. HyperSQL also supports LONGVARCHAR
      as a synonym for VARCHAR. If LONGVARCHAR is used without a length, then
      a length of 16M is assigned. You can set LONGVARCHAR to map to CLOB,
      with the <code class="literal">sql.longvar_is_lob</code> connection property or
      the SET DATABASE SQL LONGVAR IS LOB TRUE statement..</p>
<p>HyperSQL's default character set is Unicode, therefore all
      possible character strings can be represented by these types.</p>
<p>The SQL Standard behaviour of the CHARACTER type is a remnant of
      legacy systems in which character strings are padded with spaces to fill
      a fixed width. These spaces are sometimes significant while in other
      cases they are silently discarded. It would be best to avoid the
      CHARACTER type altogether. With the rest of the types, the strings are
      not padded when assigned to columns or variables of the given type. The
      trailing spaces are still considered discardable for all character
      types. Therefore if a string with trailing spaces is too long to assign
      to a column or variable of a given length, the spaces beyond the type
      length are discarded and the assignment succeeds (provided all the
      characters beyond the type length are spaces).</p>
<p>The VARCHAR and CLOB types have length limits, but the strings are
      not padded by the system. Note that if you use a large length for a
      VARCHAR or CLOB type, no extra space is used in the database. The space
      used for each stored item is proportional to its actual length.</p>
<p>If CHARACTER is used without specifying the length, the length
      defaults to 1. For the CLOB type, the length limit can be defined in
      units of kilobyte (K, 1024), megabyte (M, 1024 * 1024) or gigabyte (G,
      1024 * 1024 * 1024), using the <code class="literal">&lt;multiplier&gt;</code>. If
      CLOB is used without specifying the length, the length defaults to
      1GB.</p>
<p>
<code class="literal">&lt;character string type&gt; ::= { CHARACTER | CHAR }
      [ &lt;left paren&gt; &lt;character length&gt; &lt;right paren&gt; ] | {
      CHARACTER VARYING | CHAR VARYING | VARCHAR } &lt;left paren&gt;
      &lt;character length&gt; &lt;right paren&gt; | LONGVARCHAR [ &lt;left
      paren&gt; &lt;character length&gt; &lt;right paren&gt; ] | &lt;character
      large object type&gt;</code>
</p>
<p>
<code class="literal">&lt;character large object type&gt; ::= { CHARACTER
      LARGE OBJECT | CHAR LARGE OBJECT | CLOB } [ &lt;left paren&gt;
      &lt;character large object length&gt; &lt;right paren&gt;
      ]</code>
</p>
<p>
<code class="literal">&lt;character length&gt; ::= &lt;unsigned integer&gt;
      [ &lt;char length units&gt; ]</code>
</p>
<p>
<code class="literal">&lt;large object length&gt; ::= &lt;length&gt; [
      &lt;multiplier&gt; ] | &lt;large object length
      token&gt;</code>
</p>
<p>
<code class="literal">&lt;character large object length&gt; ::= &lt;large
      object length&gt; [ &lt;char length units&gt; ]</code>
</p>
<p>
<code class="literal">&lt;large object length token&gt; ::= &lt;digit&gt;...
      &lt;multiplier&gt;</code>
</p>
<p>
<code class="literal">&lt;multiplier&gt; ::= K | M | G </code>
</p>
<p>
<code class="literal">&lt;char length units&gt; ::= CHARACTERS |
      OCTETS</code>
</p>
<p>Each character type has a collation. This is either a default
      collation or stated explicitly with the COLLATE clause. Collations are
      discussed in the <a class="link" href="#databaseobjects-chapt" title="Chapter&nbsp;4.&nbsp;Schemas and Database Objects">Schemas and Database Objects</a> chapter.</p>
<pre class="programlisting"> CHAR(10)
 CHARACTER(10)
 VARCHAR(2)
 CHAR VARYING(2)
 CLOB(1000)
 CLOB(30K)
 CHARACTER LARGE OBJECT(1M)
 LONGVARCHAR
</pre>
</div>
<div class="section" title="Binary String Types">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="sgc_binary_types"></a>Binary String Types</h3>
</div>
</div>
</div>
<a name="N10546" class="indexterm"></a>
<p>The BINARY, BINARY VARYING and BLOB types are the SQL Standard
      binary string types. VARBINARY and BINARY LARGE OBJECT are synonyms for
      BINARY VARYING and BLOB types. HyperSQL also supports LONGVARBINARY as a
      synonym for VARBINARY. You can set LONGVARBINARY to map to BLOB, with
      the <code class="literal">sql.longvar_is_lob</code> connection property or the SET
      DATABASE SQL LONGVAR IS LOB TRUE statement.</p>
<p>Binary string types are used in a similar way to character string
      types. There are several built-in functions that are overloaded to
      support character, binary and bit strings.</p>
<p>The BINARY type represents a fixed width-string. Each shorter
      string is padded with zeros to fill the fixed width. Similar to the
      CHARACTER type, the trailing zeros in the BINARY string are simply
      discarded in some operations. For the same reason, it is best to avoid
      this particular type and use VARBINARY instead.</p>
<p>When two binary values are compared, if one is of BINARY type,
      then zero padding is performed to extend the length of the shorter
      string to the longer one before comparison. No padding is performed with
      other binary types. If the bytes compare equal to the end of the shorter
      value, then the longer string is considered larger than the shorter
      string.</p>
<p>If BINARY is used without specifying the length, the length
      defaults to 1. For the BLOB type, the length limit can be defined in
      units of kilobyte (K, 1024), megabyte (M, 1024 * 1024) or gigabyte (G,
      1024 * 1024 * 1024), using the <code class="literal">&lt;multiplier&gt;</code>. If
      BLOB is used without specifying the length, the length defaults to
      1GB.</p>
<p>
<code class="literal">&lt;binary string type&gt; ::= BINARY [ &lt;left
      paren&gt; &lt;length&gt; &lt;right paren&gt; ] | { BINARY VARYING |
      VARBINARY } &lt;left paren&gt; &lt;length&gt; &lt;right paren&gt; |
      LONGVARBINARY [ &lt;left paren&gt; &lt;length&gt; &lt;right paren&gt; ]
      | &lt;binary large object string type&gt;</code>
</p>
<p>
<code class="literal">&lt;binary large object string type&gt; ::= { BINARY
      LARGE OBJECT | BLOB } [ &lt;left paren&gt; &lt;large object length&gt;
      &lt;right paren&gt; ]</code>
</p>
<p>
<code class="literal">&lt;length&gt; ::= &lt;unsigned
      integer&gt;</code>
</p>
<pre class="programlisting"> BINARY(10)
 VARBINARY(2)
 BINARY VARYING(2)
 BLOB(1000)
 BLOB(30G)
 BINARY LARGE OBJECT(1M)
 LONGVARBINARY
</pre>
</div>
<div class="section" title="Bit String Types">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="sgc_bit_types"></a>Bit String Types</h3>
</div>
</div>
</div>
<a name="N1056A" class="indexterm"></a>
<p>The BIT and BIT VARYING types are the supported bit string types.
      These types were defined by SQL:1999 but were later removed from the
      Standard. Bit types represent bit maps of given lengths. Each bit is 0
      or 1. The BIT type represents a fixed width-string. Each shorter string
      is padded with zeros to fill the fixed with. If BIT is used without
      specifying the length, the length defaults to 1. The BIT VARYING type
      has a maximum width and shorter strings are not padded.</p>
<p>Before the introduction of the BOOLEAN type to the SQL Standard, a
      single-bit string of the type BIT(1) was commonly used. For
      compatibility with other products that do not conform to, or extend, the
      SQL Standard, HyperSQL allows values of BIT and BIT VARYING types with
      length 1 to be converted to and from the BOOLEAN type. BOOLEAN TRUE is
      considered equal to B'1', BOOLEAN FALSE is considered equal to
      B'0'.</p>
<p>For the same reason, numeric values can be assigned to columns and
      variables of the type BIT(1). For assignment, the numeric value zero is
      converted to B'0', while all other values are converted to B'1'. For
      comparison, numeric values 1 is considered equal to B'1' and numeric
      value zero is considered equal to B'0'.</p>
<p>It is not allowed to perform other arithmetic or boolean
      operations involving BIT(1) and BIT VARYING(1). The kid of operations
      allowed on bit strings are analogous to those allowed on BINARY and
      CHARACTER strings. Several built-in functions support all three types of
      string.</p>
<p>
<code class="literal">&lt;bit string type&gt; ::= BIT [ &lt;left paren&gt;
      &lt;length&gt; &lt;right paren&gt; ] | BIT VARYING &lt;left paren&gt;
      &lt;length&gt; &lt;right paren&gt;</code>
</p>
<pre class="programlisting"> BIT
 BIT(10)
 BIT VARYING(2)
</pre>
</div>
<div class="section" title="Lob Data">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="sgc_lob_data"></a>Lob Data</h3>
</div>
</div>
</div>
<p>BLOB and CLOB are lob types. These types are used for very long
      strings that do not necessarily fit in memory. Small lobs that fit in
      memory can be accessed just like BINARY or VARCHAR column data. But lobs
      are usually much larger and therefore accessed with special JDBC
      methods.</p>
<p>To insert a lob into a table, or to update a column of lob type
      with a new lob, you can use the <code class="literal">setBinaryStream()</code> and
      <code class="literal">setCharacterStream()</code> methods of JDBC
      <code class="literal">java.sql.PreparedStatement</code>. These are very efficient
      methods for long lobs. Other methods are also supported. If the data for
      the BLOB or CLOB is already a memory object, you can use the
      <code class="literal">setBytes()</code> or <code class="literal">setString()</code> methods,
      which are efficient for memory data. Another method is to obtain a lob
      with the <code class="literal">getBlob()</code> and <code class="literal">getClob()</code>
      methods of <code class="literal">java.sql.Connection</code>, populate its data,
      then use the <code class="literal">setBlob()</code> or
      <code class="literal">setClob()</code> methods of
      <code class="literal">PreparedStatement</code>. Yet another method allows to
      create instances of <code class="literal">org.hsqldb.jdbc.JDBCBlobFile</code> and
      <code class="literal">org.hsqldb.jdbc.JDBCClobFile</code> and construct a large
      lob for use with <code class="literal">setBlob()</code> and
      <code class="literal">setClob()</code> methods.</p>
<p>A lob is retrieved from a ResultSet with the
      <code class="literal">getBlob()</code> or <code class="literal">getClob()</code> method. The
      steaming methods of the lob objects are then used to access the data.
      HyperSQL also allows efficient access to chunks of lobs with
      <code class="literal">getBytes()</code> or <code class="literal">getString()</code> methods.
      Furthermore, parts of a BLOB or CLOB already stored in a table can be
      modified. An updatable <code class="literal">ResultSet</code> is used to select
      the row from the table. The <code class="literal">getBlob()</code> or
      <code class="literal">getClob()</code> methods of <code class="literal">ResultSet</code> are
      used to access the lob as a <code class="literal">java.sql.Blob</code> or
      <code class="literal">java.sql.Clob</code> object. The
      <code class="literal">setBytes()</code> and <code class="literal">setString()</code> methods
      of these objects can be used to modify the lob. Finally the
      <code class="literal">updateRow()</code> method of the
      <code class="literal">ResultSet</code> is used to update the lob in the row. Note
      these modifications are not allowed with compressed or encrypted
      lobs.</p>
<p>Lobs are logically stored in columns of tables. Their physical
      storage is a separate *.lobs file. This file is created as soon as a
      BLOB or CLOB is inserted into the database. The file will grow as new
      lobs are inserted into the database. In version 2, the *.lobs file is
      never deleted even if all lobs are deleted from the database. In this
      case you can delete the *.lobs file after a SHUTDOWN. When a CHECKPOINT
      happens, the space used for deleted lobs is freed and is reused for
      future lobs. By default, clobs are stored without compression. You can
      use a database setting to enable compression of clobs. This can
      significantly reduce the storage size of clobs.</p>
</div>
<div class="section" title="Storage and Handling of Java Objects">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="sgc_java_objects"></a>Storage and Handling of Java Objects</h3>
</div>
</div>
</div>
<a name="N105E3" class="indexterm"></a>
<p>Any serializable JAVA Object can be inserted directly into a
      column of type OTHER using any variation of
      <code class="methodname">PreparedStatement.setObject()</code> methods.</p>
<p>For comparison purposes and in indexes, any two Java Objects are
      considered equal unless one of them is NULL. You cannot search for a
      specific object or perform a join on a column of type OTHER.</p>
<p>Please note that HSQLDB is not an object-relational database. Java
      Objects can simply be stored internally and no operations should be
      performed on them other than assignment between columns of type OTHER or
      tests for NULL. Tests such as <code class="literal">WHERE object1 = object2
      </code>do not mean what you might expect, as any non-null object
      would satisfy such a tests. But <code class="literal">WHERE object1 IS NOT
      NULL</code> is perfectly acceptable.</p>
<p>The engine does not allow normal column values to be assigned to
      Java Object columns (for example, assigning an INTEGER or STRING to such
      a column with an SQL statement such as <code class="literal">UPDATE mytable SET
      objectcol = intcol WHERE ...</code>).</p>
<p>
<code class="literal">&lt;java object type&gt; ::= OTHER</code>
</p>
</div>
<div class="section" title="Type Length, Precision and Scale">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="sgc_length_precision"></a>Type Length, Precision and Scale</h3>
</div>
</div>
</div>
<p>In older version of HyperSQL, all table column type definitions
      with a column length, precision or scale qualifier were accepted and
      ignored. HSQLDB 1.8 enforced correctness but included an option to
      enforce the length, precision or scale.</p>
<p>In HyperSQL 2, length, precision and scale qualifiers are always
      enforced. For backward compatibility, when older databases which had the
      property hsqldb.enforce_strict_size=false are converted to version 2,
      this property is retained. However, this is a temporary measure. You
      should test your application to ensure the length, precision and scale
      that is used for column definitions is appropriate for the application
      data. You can test with the default database setting, which enforces the
      sizes.</p>
<p>String types, including all BIT, BINARY and CHAR string types plus
      CLOB and BLOB, are generally defined with a length. If no length is
      specified for BIT, BINARY and CHAR, the default length is 1. For CLOB
      and BLOB an implementation defined length of 1M is used.</p>
<p>TIME and TIMESTAMP types can be defined with a fractional second
      precision between 0 and 9. INTERVAL type definition may have precision
      and, in some cases, fraction second precision. DECIMAL and NUMERIC types
      may be defined with precision and scale. For all of these types a
      default precision or scale value is used if one is not specified. The
      default scale is 0. The default fractional precision for TIME is 0,
      while it is 6 for TIMESTAMP.</p>
<p>Values can be converted from one type to another in two different
      ways: by using explicit CAST expression or by implicit conversion used
      in assignment, comparison and aggregation.</p>
<p>String values cannot be assigned to VARCHAR columns if they are
      longer than the defined type length. For CHARACTER columns, a long
      string can be assigned (with truncation) only if all the characters
      after the length are spaces. Shorter strings are padded with the space
      character when inserted into a CHARACTER column. Similar rules are
      applied to VARBINARY and BINARY columns. For BINARY columns, the padding
      and truncation rules are applied with zero bytes, instead of
      spaces.</p>
<p>Explicit CAST of a value to a CHARACTER or VARCHAR type will
      result in forced truncation or padding. So a test such as <code class="literal">CAST
      (mycol AS VARCHAR(2)) = 'xy'</code> will find the values beginning
      with 'xy'. This is the equivalent of <code class="literal">SUBSTRING(mycol FROM 1 FOR
      2)= 'xy'</code>.</p>
<p>For all numeric types, the rules of explicit cast and implicit
      conversion are the same. If cast or conversion causes any digits to be
      lost from the fractional part, it can take place. If the non-fractional
      part of the value cannot be represented in the new type, cast or
      conversion cannot take place and will result in a data exception.</p>
<p>There are special rules for DATE, TIME, TIMESTAMP and INTERVAL
      casts and conversions.</p>
</div>
</div>
<div class="section" title="Datetime types">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="sgc_datetime_types"></a>Datetime types</h2>
</div>
</div>
</div>
<p>HSQLDB fully supports datetime and interval types and operations,
    including all relevant optional features, as specified by the SQL Standard
    since SQL-92. The two groups of types are complementary.</p>
<a name="N10621" class="indexterm"></a>
<p>The DATE type represents a calendar date with YEAR, MONTH and DAY
    fields.</p>
<p>The TIME type represents time of day with HOUR, MINUTE and SECOND
    fields, plus an optional SECOND FRACTION field.</p>
<p>The TIMESTAMP type represents the combination of DATE and TIME
    types.</p>
<p>TIME and TIMESTAMP types can include WITH TIME ZONE or WITHOUT TIME
    ZONE (the default) qualifiers. They can have fractional second parts. For
    example, TIME(6) has six fractional digits for the second field.</p>
<p>If fractional second precision is not specified, it defaults to 0
    for TIME and to 6 for TIMESTAMP.</p>
<p>
<code class="literal">&lt;datetime type&gt; ::= DATE | TIME [ &lt;left
    paren&gt; &lt;time precision&gt; &lt;right paren&gt; ] [ &lt;with or
    without time zone&gt; ] | TIMESTAMP [ &lt;left paren&gt; &lt;timestamp
    precision&gt; &lt;right paren&gt; ] [ &lt;with or without time zone&gt;
    ]</code>
</p>
<p>
<code class="literal">&lt;with or without time zone&gt; ::= WITH TIME ZONE |
    WITHOUT TIME ZONE</code>
</p>
<p>
<code class="literal">&lt;time precision&gt; ::= &lt;time fractional seconds
    precision&gt;</code>
</p>
<p>
<code class="literal">&lt;timestamp precision&gt; ::= &lt;time fractional
    seconds precision&gt;</code>
</p>
<p>
<code class="literal">&lt;time fractional seconds precision&gt; ::=
    &lt;unsigned integer&gt;</code>
</p>
<pre class="programlisting"> DATE
 TIME(6)
 TIMESTAMP(2) WITH TIME ZONE
</pre>
<p>Examples of the string literals used to represent date time values,
    some with time zone, some without, are below:</p>
<pre class="programlisting"> DATE '2008-08-22'
 TIMESTAMP '2008-08-08 20:08:08'
 TIMESTAMP '2008-08-08 20:08:08+8:00' /* Beijing */
 TIME '20:08:08.034900'
 TIME '20:08:08.034900-8:00' /* US Pacific */</pre>
<a name="N10645" class="indexterm"></a>
<p>
<span class="bold"><strong>Time Zone</strong></span>
</p>
<p>DATE values do not take time zones. For example United Nations
    designates 5 June as World Environment Day, which was observed on DATE
    '2008-06-05' in different time zones.</p>
<p>TIME and TIMESTAMP values without time zone, usually have a context
    that indicates some local time zone. For example, a database for college
    course timetables usually stores class dates and times without time zones.
    This works because the location of the college is fixed and the time zone
    displacement is the same for all the values. Even when the events take
    place in different time zones, for example international flight times, it
    is possible to store all the datetime information as references to a
    single time zone, usually GMT. For some databases it may be useful to
    store the time zone displacement together with each datetime value. SQL&rsquo;s
    TIME WITH TIME ZONE and TIMESTAMP WITH TIME ZONE values include a time
    zone displacement value.</p>
<p>The time zone displacement is of the type INTERVAL HOUR TO MINUTE.
    This data type is described in the next section. The legal values are
    between '&ndash;14:00' and &nbsp; '+14:00'.</p>
<a name="N10654" class="indexterm"></a>
<p>
<span class="bold"><strong>Operations on Datetime
    Types</strong></span>
</p>
<p>The expression <code class="literal">&lt;datetime expression&gt; AT TIME ZONE
    &lt;time displacement&gt;</code> evaluates to a datetime value
    representing exactly the same point of time in the specified
    <code class="literal">&lt;time displacement&gt;</code>. The expression, <code class="literal">AT
    LOCAL</code> is equivalent to <code class="literal">AT TIME ZONE &lt;local time
    displacement&gt;</code>. If <code class="literal">AT TIME ZONE</code> is used
    with a datetime operand of type WITHOUT TIME ZONE, the operand is first
    converted to a value of type WITH TIME ZONE at the session&rsquo;s time
    displacement, then the specified time zone displacement is set for the
    value. Therefore, in these cases, the final value depends on the time zone
    of the session in which the statement was used.</p>
<p>AT TIME ZONE, modifies the field values of the datetime operand.
    This is done by the following procedure:</p>
<div class="orderedlist">
<ol class="orderedlist" type="1">
<li class="listitem">
<p>determine the corresponding datetime at UTC.</p>
</li>
<li class="listitem">
<p>find the datetime value at the given time zone that corresponds
        with the UTC value from step 1.</p>
</li>
</ol>
</div>
<p>Example a:</p>
<pre class="programlisting"> TIME '12:00:00' AT TIME ZONE INTERVAL '1:00' HOUR TO MINUTE
</pre>
<p>If the session&rsquo;s time zone displacement is -'8:00', then in step 1,
    TIME '12:00:00' is converted to UTC, which is TIME '20:00:00+0:00'. In
    step 2, this value is expressed as TIME '21:00:00+1:00'.</p>
<p>Example b:</p>
<pre class="programlisting"> TIME '12:00:00-5:00' AT TIME ZONE INTERVAL '1:00' HOUR TO MINUTE
</pre>
<p>Because the operand has a time zone, the result is independent of
    the session &nbsp;time zone displacement. Step 1 results in TIME
    '17:00:00+0:00', and step 2 results in TIME '18:00:00+1:00'</p>
<p>Note that the operand is not limited to datetime literals used in
    these examples. Any valid expression that evaluates to a datetime value
    can be the operand.</p>
<p>
<span class="bold"><strong>Type Conversion</strong></span>
</p>
<p>CAST is used to for all other conversions. Examples:</p>
<pre class="programlisting"> CAST (&lt;value&gt; AS TIME WITHOUT TIME ZONE)
 CAST (&lt;value&gt; AS TIME WITH TIME ZONE)</pre>
<p>In the first example, if <code class="literal">&lt;value&gt;</code> has a time
    zone component, it is simply dropped. For example TIME '12:00:00-5:00' is
    converted to TIME '12:00:00'</p>
<p>In the second example, if <code class="literal">&lt;value&gt;</code> has no
    time zone component, the current time zone displacement of the session is
    added. For example TIME '12:00:00' is converted to TIME '12:00:00-8:00'
    when the session time zone displacement is '-8:00'.</p>
<p>Conversion between DATE and TIMESTAMP is performed by removing the
    TIME component of a TIMESTAMP value or by setting the hour, minute and
    second fields to zero. TIMESTAMP '2008-08-08 20:08:08+8:00' becomes DATE
    '2008-08-08', while DATE '2008-08-22' becomes TIMESTAMP '2008-08-22
    00:00:00'.</p>
<p>Conversion between TIME and TIMESTAMP is performed by removing the
    DATE field values of a TIMESTAMP value or by appending the fields of the
    TIME value to the fields of the current session date value.</p>
<p>
<span class="bold"><strong>Assignment</strong></span>
</p>
<p>When a value is assigned to a datetime target, e.g., a value is used
    to update a row of a table, the type of the value must be the same as the
    target, but the WITH TIME ZONE or WITHOUT TIME ZONE characteristics can be
    different. If the types are not the same, an explicit CAST must be used to
    convert the value into the target type.</p>
<p>
<span class="bold"><strong>Comparison</strong></span>
</p>
<p>When values WITH TIME ZONE are compared, they are converted to UTC
    values before comparison. If a value WITH TIME ZONE is compared to another
    WITHOUT TIME ZONE, then the WITH TIME ZONE value is converted to AT LOCAL,
    then converted to WITHOUT TIME ZONE before comparison.</p>
<p>It is not recommended to design applications that rely on
    comparisons and conversions between TIME values WITH TIME ZONE. The
    conversions may involve normalisation of the time value, resulting in
    unexpected results. For example, the expression: BETWEEN(TIME
    '12:00:00-8:00', TIME '22:00:00-8:00') is converted to BETWEEN(TIME
    '20:00:00+0:00', TIME '06:00:00+0:00') when it is evaluated in the UTC
    zone, which is always FALSE.</p>
<p>
<span class="bold"><strong>Functions</strong></span>
</p>
<p>Several functions return the current session timestamp in different
    datetime types:</p>
<div class="informaltable">
<table cellspacing="0" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col>
<col>
</colgroup>
<tbody>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">
<p>CURRENT_DATE</p>
</td><td style="border-bottom: 0.5pt solid ; ">
<p>DATE</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">
<p>CURRENT_TIME</p>
</td><td style="border-bottom: 0.5pt solid ; ">
<p>TIME WITH TIME ZONE</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">
<p>CURRENT_TIMESTAMP</p>
</td><td style="border-bottom: 0.5pt solid ; ">
<p>TIMESTAMP WITH TIME ZONE</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">
<p>LOCALTIME</p>
</td><td style="border-bottom: 0.5pt solid ; ">
<p>TIME WITHOUT TIME ZONE</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; ">
<p>LOCALTIMESTAMP</p>
</td><td style="">
<p>TIMESTAMP WITHOUT TIME ZONE</p>
</td>
</tr>
</tbody>
</table>
</div>
<p>HyperSQL supports a very extensive range of functions for
    conversion, extraction and manipulation of DATE and TIMESTAMP values. See
    the <a class="link" href="#builtinfunctions-chapt" title="Chapter&nbsp;10.&nbsp;Built In Functions">Built In Functions</a> chapter.</p>
<p>
<span class="bold"><strong>Session Time Zone
    Displacement</strong></span>
</p>
<p>When an SQL session is started (with a JDBC connection) the local
    time zone of the client JVM (including any seasonal time adjustments such
    as daylight saving time) is used as the session time zone displacement.
    Note that the SQL session time displacement is not changed when a seasonal
    time adjustment takes place while the session is open. To change the SQL
    session time zone displacement use the following commands:</p>
<p>
<code class="literal">SET TIME ZONE &lt;time
    displacement&gt;</code>
</p>
<p>
<code class="literal">SET TIME ZONE LOCAL</code>
</p>
<p>The first command sets the displacement to the given value. The
    second command restores the original, real time zone displacement of the
    session.</p>
<p>
<span class="bold"><strong>Datetime Values and
    Java</strong></span>
</p>
<p>When datetime values are sent to the database using the
    <code class="classname">PreparedStatement</code> or
    <code class="classname">CallableStatement</code> interfaces, the Java object is
    converted to the type of the prepared or callable statement parameter.
    This type may be DATE, TIME, or TIMESTAMP (with or without time zone). The
    time zone displacement is the time zone of the JDBC session.</p>
<p>When datetime values are retrieved from the database using the
    <code class="literal">ResultSet</code> interface, there are two representations. The
    <code class="methodname">getString(&hellip;)</code> methods of the
    <code class="classname">ResultSet</code> interface, return an exact representation
    of the value in the SQL type as it is stored in the database. This
    includes the correct number of digits for the fractional second field, and
    for values with time zone displacement, the time zone displacement.
    Therefore if TIME '12:00:00' is stored in the database, all users in
    different time zones will get '12:00:00' when they retrieve the value as a
    string. The <code class="methodname">getTime(&hellip;)</code> and
    <code class="methodname">getTimestamp(&hellip;)</code> methods of the
    <code class="classname">ResultSet</code> interface return Java objects that are
    corrected for the session time zone. The UTC millisecond value contained
    the <code class="classname">java.sql.Time</code> or
    <code class="classname">java.sql.Timestamp</code> objects will be adjusted to the
    time zone of the session, therefore the
    <code class="methodname">toString()</code> method of these objects return the
    same values in different time zones.</p>
<p>If you want to store and retrieve UTC values that are independent of
    any session's time zone, you can use a TIMESTAMP WITH TIME ZONE column.
    The setTime(...) and setTimestamp(...) methods of the PreparedStatement
    interface which have a Calendar parameter can be used to assign the
    values. The time zone of the given Calendar argument is used as the time
    zone. Conversely, the getTime(...) and getTimestamp(...) methods of the
    ResultSet interface which have a Calendar parameter can be used with a
    Calendar argument to retrieve the values.</p>
<p>JDBC has an unfortunate limitation and does not include type codes
    for SQL datetime types that have a TIME ZONE property. Therefore, for
    compatibility with database tools that are limited to the JDBC type codes,
    HyperSQL reports these types by default as datetime types without TIME
    ZONE. You can use the URL property
    <code class="literal">hsqldb.translate_dti_types=false</code> to override the
    default behaviour.</p>
<p>
<span class="bold"><strong>Non-Standard
    Extensions</strong></span>
</p>
<p>HyperSQL version 2.3.0 supports some extenstions to the SQL standard
    treatment of datetime and interval types. For example, the Standard
    expression to add a number of days to a date has an explicit INTERVAL
    value but HSQLDB also allows an integer to be used without specifying DAY.
    Examples of some Standard expressions and their non-standard alternatives
    are given below:</p>
<div class="informalexample">
<pre class="programlisting"> -- standard forms
 CURRENT_DATE + '2' DAY
 SELECT (LOCALTIMESTAMP - atimestampcolumn) DAY TO SECOND FROM atable

 -- non-standard forms
 CURRENT_DATE + 2
 SELECT LOCALTIMESTAMP - atimestampcolumn FROM atable
</pre>
</div>
<p>It is recommended to use the SQL Standard syntax as it is more
    precise and avoids ambiguity.</p>
</div>
<div class="section" title="Interval Types">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="sgc_interval_typs"></a>Interval Types</h2>
</div>
</div>
</div>
<a name="N1072B" class="indexterm"></a>
<p>Interval types are used to represent differences between date time
    values. The difference between two date time values can be measured in
    seconds or in months. For measurements in months, the units YEAR and MONTH
    are available, while for measurements in seconds, the units DAY, HOUR,
    MINUTE, SECOND are available. The units can be used individually, or as a
    range. An interval type can specify the precision of the most significant
    field and the second fraction digits of the SECOND field (if it has a
    SECOND field). The default precision is 2. The default second precision is
    0.</p>
<p>
<code class="literal">&lt;interval type&gt; ::= INTERVAL &lt;interval
    qualifier&gt;</code>
</p>
<p>
<code class="literal">&lt;interval qualifier&gt; ::= &lt;start field&gt; TO
    &lt;end field&gt; | &lt;single datetime field&gt;</code>
</p>
<p>
<code class="literal">&lt;start field&gt; ::= &lt;non-second primary datetime
    field&gt; [ &lt;left paren&gt; &lt;interval leading field precision&gt;
    &lt;right paren&gt; ]</code>
</p>
<p>
<code class="literal">&lt;end field&gt; ::= &lt;non-second primary datetime
    field&gt; | SECOND [ &lt;left paren&gt; &lt;interval fractional seconds
    precision&gt; &lt;right paren&gt; ]</code>
</p>
<p>
<code class="literal">&lt;single datetime field&gt; ::= &lt;non-second primary
    datetime field&gt; [ &lt;left paren&gt; &lt;interval leading field
    precision&gt; &lt;right paren&gt; ] | SECOND [ &lt;left paren&gt;
    &lt;interval leading field precision&gt; [ &lt;comma&gt; &lt;interval
    fractional seconds precision&gt; ] &lt;right paren&gt;
    ]</code>
</p>
<p>
<code class="literal">&lt;primary datetime field&gt; ::= &lt;non-second
    primary datetime field&gt; | SECOND</code>
</p>
<p>
<code class="literal">&lt;non-second primary datetime field&gt; ::= YEAR |
    MONTH | DAY | HOUR | MINUTE</code>
</p>
<p>
<code class="literal">&lt;interval fractional seconds precision&gt; ::=
    &lt;unsigned integer&gt;</code>
</p>
<p>
<code class="literal">&lt;interval leading field precision&gt; ::=
    &lt;unsigned integer&gt;</code>
</p>
<p>Examples of INTERVAL type definition:</p>
<pre class="programlisting"> INTERVAL YEAR TO MONTH
 INTERVAL YEAR(3)
 INTERVAL DAY(4) TO HOUR
 INTERVAL MINUTE(4) TO SECOND(6)
 INTERVAL SECOND(4,6)
</pre>
<p>The word INTERVAL indicates the general type name. The rest of the
    definition is called an <code class="literal">&lt;interval qualifier&gt;</code>.
    This designation is important, as in most expressions
    <code class="literal">&lt;interval qualifier&gt;</code> is used without the word
    INTERVAL.</p>
<p>
<span class="bold"><strong>Interval Values</strong></span>
</p>
<p>An interval value can be negative, positive or zero. An interval
    type has all the datetime fields in the specified range. These fields are
    similar to those in the TIMESTAMP type. The differences are as
    follows:</p>
<p>The first field of an interval value can hold any numeric value up
    to the specified precision. For example, the hour field in HOUR(2) TO
    SECOND can hold values above 23 (up to 99). The year and month fields can
    hold zero (unlike a TIMESTAMP value) and the maximum value of a month
    field that is not the most significant field, is 11.</p>
<p>The standard function <code class="literal">ABS(&lt;interval value
    expression&gt;)</code> can be used to convert a negative interval value
    to a positive one.</p>
<p>The literal representation of interval values consists of the type
    definition, with a string representing the interval value inserted after
    the word INTERVAL. Some examples of interval literal below:</p>
<pre class="programlisting"> INTERVAL '145 23:12:19.345' DAY(3) TO SECOND(3)
 INTERVAL '3503:12:19.345' HOUR TO SECOND(3) /* equal to the first value */
 INTERVAL '19.345' SECOND(4,3) /* maximum number of digits for the second value is 4, and each value is expressed with three fraction digits. */
 INTERVAL '-23-10' YEAR(2) TO MONTH
</pre>
<p>Interval values of the types that are based on seconds can be cast
    into one another. Similarly those that are based on months can be cast
    into one another. It is not possible to cast or convert a value based on
    seconds to one based on months, or vice versa.</p>
<p>When a cast is performed to a type with a smaller least-significant
    field, nothing is lost from the interval value. Otherwise, the values for
    the missing least-significant fields are discarded. Examples:</p>
<pre class="programlisting"> CAST ( INTERVAL '145 23:12:19' DAY TO SECOND AS INTERVAL DAY TO HOUR ) = INTERVAL '145 23' DAY TO HOUR
 CAST(INTERVAL '145 23' DAY TO HOUR AS INTERVAL DAY TO SECOND) = INTERVAL '145 23:00:00' DAY TO SECOND
</pre>
<p>A numeric value can be cast to an interval type. In this case the
    numeric value is first converted to a single-field INTERVAL type with the
    same field as the least significant field of the target interval type.
    This value is then converted to the target interval type For example CAST(
    22 AS INTERVAL YEAR TO MONTH) evaluates to INTERVAL '22' MONTH and then
    INTERVAL '1 10' YEAR TO MONTH. Note that SQL Standard only supports casts
    to single-field INTERVAL types, while HyperSQL allows casting to
    multi-field types as well.</p>
<p>An interval value can be cast to a numeric type. In this case the
    interval value is first converted to a single-field INTERVAL type with the
    same field as the least significant filed of the interval value. The value
    is then converted to the target type. For example CAST (INTERVAL '1-11'
    YEAR TO MONTH AS INT) evaluates to INTERVAL '23' MONTH, and then
    23.</p>
<p>An interval value can be cast into a character type, which results
    in an INTERVAL literal. A character value can be cast into an INTERVAL
    type so long as it is a string with a format compatible with an INTERVAL
    literal.</p>
<p>Two interval values can be added or subtracted so long as the types
    of both are based on the same field, i.e., both are based on MONTH or
    SECOND. The values are both converted to a single-field interval type with
    same field as the least-significant field between the two types. After
    addition or subtraction, the result is converted to an interval type that
    contains all the fields of the two original types.</p>
<p>An interval value can be multiplied or divided by a numeric value.
    Again, the value is converted to a numeric, which is then multiplied or
    divided, before converting back to the original interval type.</p>
<p>An interval value is negated by simply prefixing with the minus
    sign.</p>
<p>Interval values used in expressions are either typed values,
    including interval literals, or are interval casts. The expression:
    <code class="literal">&lt;expression&gt; &lt;interval qualifier&gt;</code> is a cast
    of the result of the <code class="literal">&lt;expression&gt;</code> into the
    INTERVAL type specified by the <code class="literal">&lt;interval qualifier&gt;. The
    cast can be formed by adding the keywords and parentheses as follows: CAST
    ( &lt;expression&gt; AS INTERVAL &lt;interval qualifier&gt;
    ).</code>
</p>
<p>
<code class="literal">The examples below feature different forms of expression
    that represent an interval value, which is then added to the given date
    literal.</code>
</p>
<pre class="programlisting"> DATE '2000-01-01' + INTERVAL '1-10' YEAR TO MONTH /* interval literal */
 DATE '2000-01-01' + '1-10' YEAR TO MONTH /* the string '1-10' is cast into INTERVAL YEAR TO MONTH */
 DATE '2000-01-01' + 22 MONTH /* the integer 22 is cast into INTERVAL MONTH, same value as above */
 DATE '2000-01-01' - 22 DAY /* the integer 22 is cast into INTERVAL DAY */
 DATE '2000-01-01' + COL2 /* the type of COL2 must be an INTERVAL type */
 DATE '2000-01-01' + COL2 MONTH /* COL2 may be a number, it is cast into a MONTH interval */
</pre>
<p>
<span class="bold"><strong>Datetime and Interval
    Operations</strong></span>
</p>
<p>An interval can be added to or subtracted from a datetime value so
    long as they have some fields in common. For example, an INTERVAL MONTH
    cannot be added to a TIME value, while an INTERVAL HOUR TO SECOND can. The
    interval is first converted to a numeric value, then the value is added
    to, or subtracted from, the corresponding field of the datetime
    value.</p>
<p>If the result of addition or subtraction is beyond the permissible
    range for the field, the field value is normalised and carried over to the
    next significant field until all the fields are normalised. For example,
    adding 20 minutes to TIME '23:50:10' will result successively in
    '23:70:10', '24:10:10' and finally TIME '00:10:10'. Subtracting 20 minutes
    from the result is performed as follows: '00:-10:10', '-1:50:10', finally
    TIME '23:50:10'. Note that if DATE or TIMESTAMP normalisation results in
    the YEAR field value out of the range (1,1000), then an exception
    condition is raised.</p>
<p>If an interval value based on MONTH is added to, or subtracted from
    a DATE or TIMESTAMP value, the result may have an invalid day (30 or 31)
    for the given result month. In this case an exception condition is
    raised.</p>
<p>The result of subtraction of two datetime expressions is an interval
    value. The two datetime expressions must be of the same type. The type of
    the interval value must be specified in the expression, using only the
    interval field names. The two datetime expressions are enclosed in
    parentheses, followed by the <code class="literal">&lt;interval qualifier&gt;</code>
    fields. In the first example below, COL1 and COL2 are of the same datetime
    type, and the result is evaluated in INTERVAL YEAR TO MONTH type.</p>
<pre class="programlisting"> (COL1 &ndash; COL2) YEAR TO MONTH /* the difference between two DATE or two TIEMSTAMP values in years and months */
 (CURRENT_DATE &ndash; COL3) DAY /* the number of days between the value of COL3 and the current date */
 (CURRENT_DATE - DATE '2000-01-01') YEAR TO MONTH /* the number of years and months since the beginning of this century */
 CURRENT_DATE - 2 DAY /* the date of the day before yesterday */
 (CURRENT_TIMESTAMP - TIMESTAMP '2009-01-01 00:00:00') DAY(4) TO SECOND(2) /* days to seconds since the given date */
</pre>
<p>The individual fields of both datetime and interval values can be
    extracted using the EXTRACT function. The same function can also be used
    to extract the time zone displacement fields of a datetime value.</p>
<p>
<code class="literal">EXTRACT ({YEAR | MONTH | DAY | HOUR | MINUTE | SECOND |
    TIMEZONE_HOUR | TIMEZONE_MINUTE | DAY_OF_WEEK | WEEK_OF_YEAR } FROM
    {&lt;datetime value&gt; | &lt;interval value&gt;})</code>
</p>
<p>The dichotomy between interval types based on seconds, and those
    based on months, stems from the fact that the different calendar months
    have different numbers of days. For example, the expression, &ldquo;nine months
    and nine days since an event&rdquo; is not exact when the date of the event is
    unknown. It can represent a period of around 284 days give or take one.
    SQL interval values are independent of any start or end dates or times.
    However, when they are added to or subtracted from certain date or
    timestamp values, the result may be invalid and cause an exception (e.g.
    adding one month to January 30 results in February 30, which is
    invalid).</p>
<p>JDBC has an unfortunate limitation and does not include type codes
    for SQL INTERVAL types. Therefore, for compatibility with database tools
    that are limited to the JDBC type codes, HyperSQL reports these types by
    default as VARCHAR. You can use the URL property
    <code class="literal">hsqldb.translate_dti_types=false</code> to override the
    default behaviour.</p>
</div>
<div class="section" title="Arrays">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="sgc_array"></a>Arrays</h2>
</div>
</div>
</div>
<p>Array are a powerful feature of SQL:2008 and can help solve many
    common problems. Arrays should not be used as a substitute for
    tables.</p>
<p>HyperSQL supports arrays of values according to the SQL:2008
    Standard.</p>
<p>Elements of the array are either NULL, or of the same data type. It
    is possible to define arrays of all supported types, including the types
    covered in this chapter and user defined types, except LOB types. An SQL
    array is one dimensional and is addressed from position 1. An empty array
    can also be used, which has no element.</p>
<p>Arrays can be stored in the database, as well as being used as
    temporary containers of values for simplifying SQL statements. They
    facilitate data exchange between the SQL engine and the user's
    application.</p>
<p>The full range of supported syntax allows array to be created, used
    in SELECT or other statements, combined with rows of tables and used in
    routine calls.</p>
<div class="section" title="Array Definition">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="sgc_array_def"></a>Array Definition</h3>
</div>
</div>
</div>
<p>The type of a table column, a routine parameter, a variable, or
      the return value of a function can be defined as an array.</p>
<p>
<code class="literal">&lt;array type&gt; ::= &lt;data type&gt; ARRAY [ &lt;left
      bracket or trigraph&gt; &lt;maximum cardinality&gt; &lt;right bracket or
      trigraph&gt; ]</code>
</p>
<p>The word ARRAY is added to any valid type definition except BLOB
      and CLOB type definitions. If the optional <code class="literal">&lt;maximum
      cardinality&gt;</code> is not used, the default value is 1024. The
      size of the array cannot be extended beyond maximum cardinality.</p>
<p>In the example below, the table contains a column of integer
      arrays and a column of varchar arrays. The VARCHAR array has an explicit
      maximum size of 10, which means each array can have between 0 and 10
      elements. The INTEGER array has the default maximum size of 1024. The
      scores column has a default clause with an empty array. The default
      clause can be defined only as <code class="literal">DEFAULT NULL</code> or
      <code class="literal">DEFAULT ARRAY[]</code> and does not allow arrays containing
      elements.</p>
<div class="informalexample">
<pre class="programlisting"> CREATE TABLE t (id INT PRIMARY KEY, scores INT ARRAY DEFAULT ARRAY[], names VARCHAR(20) ARRAY[10])</pre>
</div>
<p>An array can be constructed from value expressions or a query
      expression.</p>
<p>
<code class="literal">&lt;array value constructor by enumeration&gt; ::= ARRAY
      &lt;left bracket or trigraph&gt; &lt;array element list&gt; &lt;right
      bracket or trigraph&gt;</code>
</p>
<p>
<code class="literal">&lt;array element list&gt; ::= &lt;value expression&gt; [
      { &lt;comma&gt; &lt;value expression&gt; }... ]</code>
</p>
<p>
<code class="literal">&lt;array value constructor by query&gt; ::= ARRAY
      &lt;left paren&gt; &lt;query expression&gt; [ &lt;order by clause&gt; ]
      &lt;right paren&gt;</code>
</p>
<p>In the examples below, arrays are constructed from values, column
      references or variables, function calls, or query expressions.</p>
<div class="informalexample">
<pre class="programlisting"> ARRAY [ 1, 2, 3 ]
 ARRAY [ 'HOT', 'COLD' ]
 ARRAY [ var1, var2, CURRENT_DATE ]
 ARRAY (SELECT lastname FROM namestable ORDER BY id)
</pre>
</div>
<p>Inserting and updating a table with an ARRAY column can use array
      constructors, not only for updated column values, but also in equality
      search conditions:</p>
<div class="informalexample">
<pre class="programlisting"> INSERT INTO t VALUES 10, ARRAY[1,2,3], ARRAY['HOT', 'COLD']
 UPDATE t SET names = ARRAY['LARGE', 'SMALL'] WHERE id = 12
 UPDATE t SET names = ARRAY['LARGE', 'SMALL'] WHERE id &lt; 12 AND scores = ARRAY[3,4]
</pre>
</div>
<p>When using a PreparedStatement with an ARRAY parameter, an object
      of the type java.sql.Array must be used to set the parameter. The
      <code class="classname">org.hsqldb.jdbc.JDBCArrayBasic</code> class can be used
      for constructing a java.sql.Array object in the user's application. Code
      fragment below:</p>
<div class="informalexample">
<pre class="programlisting"> String sql = "UPDATE t SET names = ? WHERE id = ?";
 PreparedStatement ps = connection.prepareStatement(sql)
 Object[] data = new Object[]{"one", "two"};
 // default types defined in org.hsqldb.types.Type can be used
 org.hsqldb.types.Type type = org.hsqldb.types.Type.SQL_VARCHAR_DEFAULT;
 JDBCArrayBasic array = new JDBCArrayBasic(data, type);
 ps.setArray(1, array);
 ps.setInt(2, 1000);
 ps.executeUpdate();
</pre>
</div>
<div class="section" title="Trigraph">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="sgc_trigraph"></a>Trigraph</h4>
</div>
</div>
</div>
<p>A trigraph is a substitute for &lt;left bracket&gt; and
        &lt;right bracket&gt;.</p>
<p>
<code class="literal">&lt;left bracket trigraph&gt; ::= ??( </code>
</p>
<p>
<code class="literal">&lt;right bracket trigraph&gt; ::= ??)</code>
</p>
<p>The example below shows the use of trigraphs instead of
        brackets.</p>
<div class="informalexample">
<pre class="programlisting"> INSERT INTO t VALUES 10, ARRAY??(1,2,3??), ARRAY['HOT', 'COLD']
 UPDATE t SET names = ARRAY ??('LARGE', 'SMALL'??) WHERE id = 12
 UPDATE t SET names = ARRAY['LARGE', 'SMALL'] WHERE id &lt; 12 AND scores = ARRAY[3,4]
</pre>
</div>
</div>
</div>
<div class="section" title="Array Reference">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="sgc_array_ref"></a>Array Reference</h3>
</div>
</div>
</div>
<p>The most common operations on an array are element reference and
      assignment, which are used when reading or writing an element of the
      array. Unlike Java and many other languages, arrays are extended if an
      element is assigned to an index beyond the current length. This can
      result in gaps containing NULL elements. Array length cannot exceed the
      maximum cardinality.</p>
<p>Elements of all arrays, including those that are the result of
      function calls or other operations can be referenced for reading.</p>
<p>
<code class="literal">&lt;array element reference&gt; ::= &lt;array value
      expression&gt; &lt;left bracket&gt; &lt;numeric value expression&gt;
      &lt;right bracket&gt;</code>
</p>
<p>Elements of arrays that are table columns or routine variables can
      be referenced for writing. This is done in a SET statement, either
      inside an UPDATE statement, or as a separate statement in the case of
      routine variables, OUT and INOUT parameters.</p>
<p>
<code class="literal">&lt;target array element specification&gt; ::= &lt;target
      array reference&gt; &lt;left bracket or trigraph&gt; &lt;simple value
      specification&gt; &lt;right bracket or trigraph&gt;</code>
</p>
<p>
<code class="literal">&lt;target array reference&gt; ::= &lt;SQL parameter
      reference&gt; | &lt;column reference&gt;</code>
</p>
<p>Note that only simple values or variables are allowed for the
      array index when an assignment is performed. The examples below
      demonstrates how elements of the array are referenced in SELECT and an
      UPDATE statement.</p>
<div class="informalexample">
<pre class="programlisting"> SELECT scores[ranking], names[ranking] FROM t JOIN t1 on (t.id = t1.tid)
 UPDATE t SET scores[2] = 123, names[2] = 'Reds' WHERE id = 10
</pre>
</div>
<div class="informalexample">
<pre class="programlisting"> SELECT scores[ranking], names[ranking] FROM t JOIN t1 on (t.id = t1.tid)
 UPDATE t SET scores[2] = 123, names[2] = 'Reds' WHERE id = 10
</pre>
</div>
<p></p>
</div>
<div class="section" title="Array Operations">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="sgc_array_ops"></a>Array Operations</h3>
</div>
</div>
</div>
<p>Several SQL operations and functions can be used with
      arrays.</p>
<p>
<span class="emphasis"><em>CONCATENATION</em></span>
</p>
<p>Array concatenation is performed similar to string concatenation.
      All elements of the array on the right are appended to the array on
      left.</p>
<p>
<code class="literal">&lt;array concatenation&gt; ::= &lt;array value
      expression 1&gt; &lt;concatenation operator&gt; &lt;array value
      expression 2&gt;</code>
</p>
<p>
<code class="literal">&lt;concatenation operator&gt; ::= ||</code>
</p>
<p>
<span class="emphasis"><em>FUNCTIONS</em></span>
</p>
<p>Seven functions operate on arrays. Details are described in the
      <a class="link" href="#builtinfunctions-chapt" title="Chapter&nbsp;10.&nbsp;Built In Functions">Built In Functions</a> chapter.</p>
<p>
<code class="literal">ARRAY_AGG</code> is an aggregate function and produces
      an array containing values from differnt rows of a SELECT statement.
      Details are described in the <a class="link" href="#dataaccess-chapt" title="Chapter&nbsp;7.&nbsp;Data Access and Change">Data Access and Change</a> chapter.</p>
<p>
<code class="literal">SEQUENCE_ARRAY</code> creates an array with sequential
      elements.</p>
<p>
<code class="literal">CARDINALITY &lt;left paren&gt; &lt;array value
      expression&gt; &lt;right paren&gt;</code>
</p>
<p>
<code class="literal">MAX_CARDINALITY &lt;left paren&gt; &lt;array value
      expression&gt; &lt;right paren&gt;</code>
</p>
<p>Array cardinality and max cardinality are functions that return an
      integer. CARDINALITY returns the element count, while MAX_CARDINALITY
      returns the maximum declared cardinality of an array.</p>
<p>
<code class="literal">POSITION_ARRAY &lt;left paren&gt; &lt;value
      expression&gt; IN &lt;array value expression&gt; [FROM &lt;numeric value
      expression&gt;] &lt;right paren&gt;</code>
</p>
<p>The POSITION_ARRAY function returns the position of the first
      match for the &lt;value expression&gt; from the start or from the given
      start position when &lt;numeric value expression&gt; is used.</p>
<p>
<code class="literal">TRIM_ARRAY &lt;left paren&gt; &lt;array value
      expression&gt; &lt;comma&gt; &lt;numeric value expression&gt; &lt;right
      paren&gt;</code>
</p>
<p>The TRIM_ARRAY function returns a copy of an array with the
      specified number of elements removed from the end of the array. The
      <code class="literal">&lt;array value expression&gt;</code> can be any expression
      that evaluates to an array.</p>
<p>
<code class="literal">SORT_ARRAY &lt;left paren&gt; &lt;array value
      expression&gt; [ { ASC | DESC } ] [ NULLS { FIRST | LAST } ] &lt;right
      paren&gt;</code>
</p>
<p>The SORT_ARRAY function returns a sorted copy of an array. NULL
      elements appear at the beginning of the new array. You can change the
      sort direction or the position of NULL elements with the option
      keywords.</p>
<p>
<span class="emphasis"><em>CAST</em></span>
</p>
<p>An array can be cast into an array of a different type. Each
      element of the array is cast into the element type of the target array
      type.</p>
<p>
<span class="emphasis"><em>UNNEST</em></span>
</p>
<p>Arrays can be converted into table references with the UNNEST
      keyword.</p>
<p>
<code class="literal">UNNEST(&lt;array value expression&gt;) [ WITH ORDINALITY
      ]</code>
</p>
<p>The <code class="literal">&lt;array value expression&gt;</code> can be any
      expression that evaluates to an array. A table is returned that contains
      one column when WITH ORDINALITY is not used, or two columns when WITH
      ORDINALITY is used. The first column contains the elements of the array
      (including all the nulls). When the table has two columns, the second
      column contains the ordinal position of the element in the array. When
      UNNEST is used in the FROM clause of a query, it implies the LATERAL
      keyword, which means the array that is converted to table can belong to
      any table that precedes the UNNEST in the FROM clause. This is explained
      in the <a class="link" href="#dataaccess-chapt" title="Chapter&nbsp;7.&nbsp;Data Access and Change">Data Access and Change</a> chapter.</p>
<p>
<span class="emphasis"><em>INLINE CONSTRUCTOR</em></span>
</p>
<p>Array constructors can be used in SELECT and other statements. For
      example, an array constructor with a subquery can return the values from
      several rows as one array.</p>
<p>The example below shows an ARRAY constructor with a correlated
      subquery to return the list of order values for each customer. The
      CUSTOMER table that is included for tests in the DatabaseManager GUI app
      is the source of the data.</p>
<pre class="programlisting"> SELECT FIRSTNAME, LASTNAME, ARRAY(SELECT INVOICE.TOTAL FROM INVOICE WHERE CUSTOMERID = CUSTOMER.ID) AS ORDERS FROM CUSTOMER

 FIRSTNAME LASTNAME  ORDERS                                    
 --------- --------- -------------------------------------- 
 Laura     Steel     ARRAY[2700.90,4235.70]                 
 Robert    King      ARRAY[4761.60]                         
 Robert    Sommer    ARRAY[]                                
 Michael   Smith     ARRAY[3420.30]
</pre>
<p>
<span class="emphasis"><em>COMPARISON</em></span>
</p>
<p>Arrays can be compared for equality, but they cannot be compared
      for ordering values or range comparison. Array expressions are therefore
      not allowed in an ORDER BY clause, or in a comparison expression such as
      GREATER THAN. It is possible to define a UNIQUE constraint on a column
      of ARRAY type. Two arrays are equal if they have the same length and the
      values at each index position are either equal or both NULL.</p>
<p>
<span class="emphasis"><em>USER DEFINED FUNCTIONS and PROCEDURES</em></span>
</p>
<p>Array parameters, variables and return values can be specified in
      user defined functions and procedures, including aggregate functions. An
      aggregate function can return an array that contains all the scalar
      values that have been aggregated. These capabilities allow a wider range
      of applications to be covered by user defined functions and easier data
      exchange between the engine and the user's application.</p>
</div>
</div>
<div class="section" title="Indexes and Query Speed">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="sgc_index_speed"></a>Indexes and Query Speed</h2>
</div>
</div>
</div>
<p>HyperSQL supports PRIMARY KEY, UNIQUE and FOREIGN KEY constraints,
    which can span multiple columns.</p>
<p>The engine creates indexes internally to support PRIMARY KEY, UNIQUE
    and FOREIGN KEY constraints: a unique index is created for each PRIMARY
    KEY or UNIQUE constraint; an ordinary index is created for each FOREIGN
    KEY constraint.</p>
<p>HyperSQL allows defining indexes on single or multiple columns. You
    should not create duplicate user-defined indexes on the same column sets
    covered by constraints. This would result in unnecessary memory and speed
    overheads. See the discussion in the <a class="link" href="#deployment-chapt" title="Chapter&nbsp;15.&nbsp;Deployment Guide">Deployment Guide</a> chapter for more
    information.</p>
<p>Indexes are crucial for adequate query speed. When range or equality
    conditions are used e.g. <code class="literal">SELECT ... WHERE acol &gt; 10 AND bcol =
    0</code>, an index should exist on one of the columns that has a
    condition. In this example, the <code class="literal">bcol</code> column is the best
    candidate. HyperSQL always uses the best condition and index. If there are
    two indexes, one on acol, and another on bcol, it will choose the index on
    bcol.</p>
<p>Queries always return results whether indexes exist or not, but they
    return much faster when an index exists. As a rule of thumb, HSQLDB is
    capable of internal processing of queries at over 100,000 rows per second.
    Any query that runs into several seconds is clearly accessing thousands of
    rows. The query should be checked and indexes should be added to the
    relevant columns of the tables if necessary. The <code class="literal">EXPLAIN PLAN FOR
    &lt;query&gt;</code> statement can be used to see which indexes are
    used to process the query.</p>
<p>When executing a DELETE or UPDATE statement, the engine needs to
    find the rows that are to be deleted or updated. If there is an index on
    one of the columns in the WHERE clause, it is often possible to start
    directly from the first candidate row. Otherwise all the rows of the table
    have to be examined.</p>
<p>Indexes are even more important in joins between multiple tables.
    <code class="literal">SELECT ... FROM t1 JOIN t2 ON t1.c1 = t2.c2 </code> is
    performed by taking rows of t1 one by one and finding a matching row in
    t2. If there is no index on t2.c2 then for each row of t1, all the rows of
    t2 must be checked. Whereas with an index, a matching row can be found in
    a fraction of the time. If the query also has a condition on t1, e.g.,
    <code class="literal">SELECT ... FROM t1 JOIN t2 ON t1.c1 = t2.c2 WHERE t1.c3 =
    4</code> then an index on t1.c3 would eliminate the need for checking
    all the rows of t1 one by one, and will reduce query time to less than a
    millisecond per returned row. So if t1 and t2 each contain 10,000 rows,
    the query without indexes involves checking 100,000,000 row combinations.
    With an index on t2.c2, this is reduced to 10,000 row checks and index
    lookups. With the additional index on t2.c2, only about 4 rows are checked
    to get the first result row.</p>
<p>Note that in HSQLDB an index on multiple columns can be used
    internally as a non-unique index on the first column in the list. For
    example: <code class="literal">CONSTRAINT name1 UNIQUE (c1, c2, c3); </code> means
    there is the equivalent of <code class="literal">CREATE INDEX name2 ON
    atable(c1);</code>. So you do not need to specify an extra index if you
    require one on the first column of the list.</p>
<p>In HyperSQL 2, a multi-column index will speed up queries that
    contain joins or values on the first n columns of the index. You need NOT
    declare additional individual indexes on those columns unless you use
    queries that search only on a subset of the columns. For example, rows of
    a table that has a PRIMARY KEY or UNIQUE constraint on three columns or
    simply an ordinary index on those columns can be found efficiently when
    values for all three columns, or the first two columns, or the first
    column, are specified in the WHERE clause. For example, <code class="literal">SELECT
    ... FROM t1 WHERE t1.c1 = 4 AND t1.c2 = 6 AND t1.c3 = 8 </code>will use
    an index on <code class="literal">t1(c1,c2,c3)</code> if it exists.</p>
<p>A multi-column index will not speed up queries on the second or
    third column only. The first column must be specified in the JOIN .. ON or
    WHERE conditions.</p>
<p>Sometimes query speed depends on the order of the tables in the JOIN
    .. ON or FROM clauses. For example the second query below should be faster
    with large tables (provided there is an index on
    <code class="literal">TB.COL3</code>). The reason is that <code class="literal">TB.COL3</code>
    can be evaluated very quickly if it applies to the first table (and there
    is an index on <code class="literal">TB.COL3</code>):</p>
<div class="informalexample">
<pre class="programlisting"> -- TB is a very large table with only a few rows where TB.COL3 = 4

 SELECT * FROM TA JOIN TB ON TA.COL1 = TB.COL2 AND TB.COL3 = 4;
 SELECT * FROM TB JOIN TA ON TA.COL1 = TB.COL2 AND TB.COL3 = 4;</pre>
</div>
<p>The general rule is to put first the table that has a narrowing
    condition on one of its columns. In certain cases, HyperSQL 2.2.x reorders
    the joined tables if it is obvious that this will introduce a narrowing
    condition.</p>
<p>HyperSQL features automatic, on-the-fly indexes for views and
    subselects that are used in a query.</p>
<p>Indexes are used when a LIKE condition searches from the start of
    the string.</p>
<p>Indexes are used for ORDER BY clauses if the same index is used for
    selection and ordering of rows. It is possible to force the use of index
    for ORDER BY.</p>
</div>
<div class="section" title="Query Processing and Optimisation">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="sgc_query_opt"></a>Query Processing and Optimisation</h2>
</div>
</div>
</div>
<p>HyperSQL 2.2.x changes the order of tables in a query in order to
    optimise processing. This happens only when one of the tables has a
    narrowing condition and reordering does not change the result of the
    query.</p>
<div class="section" title="Indexes and Conditions">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="sgc_indexes_cond"></a>Indexes and Conditions</h3>
</div>
</div>
</div>
<p>HyperSQL optimises queries to use indexes, for all types of range
      and equality conditions, including IS NULL and NOT NULL conditions.
      Conditions can be in join or WHERE clauses, including all types of
      joins.</p>
<p>In addition, HyperSQL will use an index (if one exists) for IN
      conditions, whether constants, variable, or subqueries are used on the
      right hand side of the IN predicate. Multicolumn IN conditions can also
      use an index.</p>
<p>HyperSQL can always use indexes when several conditions are
      combined with the AND operator, choosing a conditions which can use an
      index. This now extended to all equality conditions on multiple columns
      that are part of an index.</p>
<p>HyperSQL will also use indexes when several conditions are
      combined with the OR operator and each condition can use an index (each
      condition may use a different index). For example, if a huge table has
      two separate columns for first name and last name, and both columns are
      indexed, a query such as the following example will use the indexes and
      complete in a short time:</p>
<div class="informalexample">
<pre class="programlisting"> -- TC is a very large table

 SELECT * FROM TC WHERE TC.FIRSTNAME = 'John' OR TC.LASTNAME = 'Smith' OR TC.LASTNAME = 'Williams'
</pre>
</div>
<p>Each subquery is considered a separate SELECT statement and uses
      indexes when they are available.</p>
<p>In each SELECT statement, at least one index per table can be used
      if there is a query conditions that can use the index. When conditions
      on a table are combined with the OR operator, and each condition can use
      an index, multiple indexes per table are used.</p>
</div>
<div class="section" title="Indexes and Operations">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="sgc_indexes_ops"></a>Indexes and Operations</h3>
</div>
</div>
</div>
<p>HyperSQL optimises simple row count queries in the form of
      <code class="literal">SELECT COUNT(*) FROM &lt;table&gt;</code> and returns the
      result immediately (this optimisation does not take place in MVCC
      mode).</p>
<p>HyperSQL can use an index on a column for <code class="literal">SELECT
      MAX(&lt;column&gt;) FROM &lt;table&gt;</code> and <code class="literal">SELECT
      MIN(&lt;column&gt;) FROM &lt;table&gt;</code> queries. There should
      be an index on the &lt;column&gt; and the query can have a WHERE
      condition on the same column. In the example below the maximum value for
      the TB.COL3 below 1000000 is returned.</p>
<div class="informalexample">
<pre class="programlisting"> SELECT MAX(TB.COL3) FROM TB WHERE TB.COL &lt; 1000000
</pre>
</div>
<p>HyperSQL can use an index for simple queries containing DISTINCT
      or GROUP BY to avoid checking all the rows of the table. Note that
      indexes are always used if the query has a condition, regardless of the
      use of DISTINCT or GROUP BY. This particular optimisation applies to
      cases in which all the columns in the SELECT list are from the same
      table and are covered by a single index, and any join or query condition
      uses this index.</p>
<p>For example, with the large table below, a DISTINCT or GROUP BY
      query to return all the last names, can use an the index on the
      TC.LASTNAME column. Similarly, a GROUP BY query on two columns can use
      an index that covers the two columns.</p>
<pre class="programlisting"> -- TC is a very large table

 SELECT DISTINCT LASTNAME FROM TC WHERE TC.LASTNAME &gt; 'F'
 SELECT STATE, LASTNAME FROM TC GROUP BY STATE, LASTNAME
</pre>
</div>
<div class="section" title="Indexes and ORDER BY, OFFSET and LIMIT">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="sgc_indexes_order"></a>Indexes and ORDER BY, OFFSET and LIMIT</h3>
</div>
</div>
</div>
<p>HyperSQL can use an index on an ORDER BY clause if all the columns
      in ORDER BY are in a single-column or multi-column index (in the exact
      order). This is important if there is a LIMIT n (or FETCH n ROWS ONLY)
      clause. In this situation, the use of index allows the query processor
      to access only the number of rows specified in the LIMIT clause, instead
      of building the whole result set, which can be huge. This also works for
      joined tables when the ORDER BY clause is on the columns of the first
      table in a join. Indexes are used in the same way when ORDER BY ... DESC
      is specified in the query. Note that unlike some other RDBMS, HyperSQL
      does not need or create DESC indexes. It can use any ordinary, ascending
      index for ORDER BY ... DESC.</p>
<p>If there is an equality or range condition (e.g. EQUALS, GREATER
      THAN) condition on the columns specified in the ORDER BY clause, the
      index is still used.</p>
<p>In the two examples below, the index on TA.COL3 is used and only
      up to 1000 rows are processed and returned.</p>
<div class="informalexample">
<pre class="programlisting"> -- TA is a very large table with an index on TA.COL3

 SELECT * FROM TA JOIN TB ON TA.COL2 = TB.COL1 WHERE TA.COL3 &gt; 40000 ORDER BY TA.COL3 LIMIT 1000;
 SELECT * FROM TA JOIN TB ON TA.COL2 = TB.COL1 WHERE TA.COL3 &gt; 40000 AND TA.COL3 &lt; 100000 ORDER BY TA.COL3 DESC LIMIT 1000;
</pre>
</div>
<p>But if the query contains an equality condition on another indexed
      column in the table, this may take precedence and no index may be used
      for ORDER BY. In this case USING INDEX can be added to the end of the
      query to force the use of the index for the LIMIT operation. In the
      example below there is an index on TA.COL1 as well as the index on
      TA.COL3. Normally the index on TA.COL1 is used, but the USING INDEX hint
      results in the index on TB.COL3 to be used for selecting the first 1000
      rows.</p>
<div class="informalexample">
<pre class="programlisting"> -- TA is a very large table with an index on TA.COL3 and a separate index on TA.COL1

 SELECT * FROM TA JOIN TB ON TA.COL2 = TB.COL1 WHERE TA.COL1 = 'SENT' AND TB.COL3 &gt; 40000 ORDER BY TB.COL3 LIMIT 1000 USING INDEX;
</pre>
</div>
<p></p>
</div>
</div>
</div>
<div class="chapter" title="Chapter&nbsp;3.&nbsp;Sessions and Transactions">
<div class="titlepage">
<div>
<div>
<h2 class="title">
<a name="sessions-chapt"></a>Chapter&nbsp;3.&nbsp;Sessions and Transactions</h2>
</div>
<div>
<div class="authorgroup">
<div class="author">
<h3 class="author">
<span class="firstname">Fred</span> <span class="surname">Toussi</span>
</h3>
<div class="affiliation">
<span class="orgname">The HSQL Development Group<br>
</span>
</div>
</div>
</div>
</div>
<div>
<p class="releaseinfo">$Revision: 5212 $</p>
</div>
<div>
<div class="legalnotice" title="Legal Notice">
<a name="N1093E"></a>
<p>Copyright 2010-2012 Fred Toussi. Permission is granted to
      distribute this document without any alteration under the terms of the
      HSQLDB license. Additional permission is granted to the HSQL Development
      Group to distribute this document with or without alterations under the
      terms of the HSQLDB license.</p>
</div>
</div>
<div>
<p class="pubdate">2014-02-13 18:21:41-0500</p>
</div>
</div>
</div>
<div class="toc">
<p>
<b>Table of Contents</b>
</p>
<dl>
<dt>
<span class="section"><a href="#snc_overview">Overview</a></span>
</dt>
<dt>
<span class="section"><a href="#snc_session_attr_vars">Session Attributes and Variables</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#snc_session_attr">Session Attributes</a></span>
</dt>
<dt>
<span class="section"><a href="#snc_session_vars">Session Variables</a></span>
</dt>
<dt>
<span class="section"><a href="#snc_session_tables">Session Tables</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#snc_tx_tx_cc">Transactions and Concurrency Control</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#snc_tx_2pl">Two Phase Locking</a></span>
</dt>
<dt>
<span class="section"><a href="#snc_tx_2pl_si">Two Phase Locking with Snapshot Isolation</a></span>
</dt>
<dt>
<span class="section"><a href="#snc_tx_locks_2pl">Lock Contention in 2PL</a></span>
</dt>
<dt>
<span class="section"><a href="#snc_tx_locks_routines">Locks in SQL Routines and Triggers</a></span>
</dt>
<dt>
<span class="section"><a href="#snc_tx_mvcc">MVCC</a></span>
</dt>
<dt>
<span class="section"><a href="#snc_tx_choosing">Choosing the Transaction Model</a></span>
</dt>
<dt>
<span class="section"><a href="#snc_tx_schema_change">Schema and Database Change</a></span>
</dt>
<dt>
<span class="section"><a href="#snc_tx_access_tables">Simultaneous Access to Tables</a></span>
</dt>
<dt>
<span class="section"><a href="#snc_viewing_sessions">Viewing Sessions</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#snc_statements">Session and Transaction Control Statements</a></span>
</dt>
</dl>
</div>
<div class="section" title="Overview">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="snc_overview"></a>Overview</h2>
</div>
</div>
</div>
<p>All SQL statements are executed in sessions. When a connection is
    established to the database, a session is started. The authorization of
    the session is the name of the user that started the session. A session
    has several properties. These properties are set by default at the start
    according to database settings.</p>
<p>SQL Statements are generally transactional statements. When a
    transactional statement is executed, it starts a transaction if no
    transaction is in progress. If SQL Data is modified during a transaction,
    the change can be undone with a ROLLBACK statement. When a COMMIT
    statement is executed, the transaction is ended. If a single statement
    fails, the transaction is not normally terminated. However, some failures
    are caused by execution of statements that are in conflict with statements
    executed in other concurrent sessions. Such failures result in an implicit
    ROLLBACK, in addition to the exception that is raised.</p>
<p>Schema definition and manipulation statements are also transactional
    according to the SQL Standard. HyperSQL 2.0 performs automatic commits
    before and after the execution of such transactions. Therefore,
    schema-related statements cannot be rolled back. This is likely to change
    in future versions.</p>
<p>Some statements are not transactional. Most of these statements are
    used to change the properties of the session. These statements begin with
    the SET keyword.</p>
<p>If the AUTOCOMMIT property of a session is TRUE, then each
    transactional statement is followed by an implicit COMMIT.</p>
<p>The default isolation level for a session is READ COMMITTED. This
    can be changed using the JDBC <code class="classname">java.sql.Connection</code>
    object and its <code class="methodname">setTransactionIsolation(int level)</code>
    method. The session can be put in read-only mode using the
    <code class="methodname">setReadOnly(boolean readOnly)</code> method. Both
    methods can be invoked only after a commit or a rollback, but not during a
    transaction.</p>
<p>The isolation level and / or the readonly mode of a transaction
    can also be modified using an SQL statement. You can use the statement to
    change only the isolation mode, only the read-only mode, or both at the
    same time. This command can be issued only after a commit or
    rollback.</p>
<p>
<code class="literal">SET TRANSACTION &lt;transaction characteristic&gt; [
    &lt;comma&gt; &lt;transaction characteristic&gt; ]</code>
</p>
<p>Details of the statement is described later in this chapter.</p>
</div>
<div class="section" title="Session Attributes and Variables">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="snc_session_attr_vars"></a>Session Attributes and Variables</h2>
</div>
</div>
</div>
<p>Each session has several system attributes. A session can also have
    user-defined session variables.</p>
<div class="section" title="Session Attributes">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="snc_session_attr"></a>Session Attributes</h3>
</div>
</div>
</div>
<p>The system attributes reflect the current mode of operation for
      the session. These attributes can be accessed with function calls and
      can be referenced in queries. For example, they can be returned using
      the <code class="literal">VALUES &lt;attribute function&gt;, ...</code>
      statement.</p>
<p>The named attributes such as CURRENT_USER, CURRENT_SCHEMA, etc.
      are SQL Standard functions. Other attributes of the session, such as
      auto-commit or read-only modes can be read using other built-in
      functions. All these functions are listed in the <a class="link" href="#builtinfunctions-chapt" title="Chapter&nbsp;10.&nbsp;Built In Functions">Built In Functions</a> chapter.</p>
</div>
<div class="section" title="Session Variables">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="snc_session_vars"></a>Session Variables</h3>
</div>
</div>
</div>
<p>Session variables are user-defined variables created the same way
      as the variables for stored procedures and functions. Currently, these
      variables cannot be used in general SQL statements. They can be assigned
      to IN, INOUT and OUT parameters of stored procedures. This allows
      calling stored procedures which have INOUT or OUT arguments and is
      useful for development and debugging. See the example in the <a class="link" href="#sqlroutines-chapt" title="Chapter&nbsp;8.&nbsp;SQL-Invoked Routines">SQL-Invoked Routines</a>
      chapter, under Formal Parameters.</p>
<div class="example">
<a name="N10980"></a>
<p class="title">
<b>Example&nbsp;3.1.&nbsp;User-defined Session Variables</b>
</p>
<div class="example-contents">
<pre class="screen"> DECLARE counter INTEGER DEFAULT 3;
 DECLARE result VARCHAR(20) DEFAULT NULL;
 SET counter=15;
 CALL myroutine(counter, result)
</pre>
</div>
</div>
<br class="example-break">
</div>
<div class="section" title="Session Tables">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="snc_session_tables"></a>Session Tables</h3>
</div>
</div>
</div>
<p>With necessary access privileges, sessions can access all table,
      including GLOBAL TEMPORARY tables, that are defined in schemas. Although
      GLOBAL TEMPORARY tables have a single name and definition which applies
      to all sessions that use them, the contents of the tables are different
      for each session. The contents are cleared either at the end of each
      transaction or when the session is closed.</p>
<p>Session tables are different because their definition is visible
      only within the session that defines a table. The definition is dropped
      when the session is closed. Session tables do not belong to
      schemas.</p>
<p>
<code class="literal">&lt;temporary table declaration&gt; ::= DECLARE LOCAL
      TEMPORARY TABLE &lt;table name&gt; &lt;table element list&gt; [ ON
      COMMIT { PRESERVE | DELETE } ROWS ]</code>
</p>
<p>The syntax for declaration is based on the SQL Standard. A session
      table cannot have FOREIGN KEY constraints, but it can have PRIMARY KEY,
      UNIQUE or CHECK constraints. A session table definition cannot be
      modified by adding or removing columns, indexes, etc.</p>
<p>It is possible to refer to a session table using its name, which
      takes precedence over a schema table of the same name. To distinguish a
      session table from schema tables, the pseudo schema names, MODULE or
      SESSION can be used. An example is given below:</p>
<div class="example">
<a name="N10995"></a>
<p class="title">
<b>Example&nbsp;3.2.&nbsp;User-defined Temporary Session Tables</b>
</p>
<div class="example-contents">
<pre class="screen"> DECLARE LOCAL TEMPORARY TABLE buffer (id INTEGER PRIMARY KEY, textdata VARCHAR(100)) ON COMMIT PRESERVE ROWS
 INSERT INTO module.buffer SELECT id, firstname || ' ' || lastname FROM customers
 -- do some more work
 DROP TABLE module.buffer
 -- or use alternative pseudo schema name
 DROP TABLE session.buffer
</pre>
</div>
</div>
<p>
<br class="example-break">Session tables can be created inside a transaction.
      Automatic indexes are created and used on session tables when necessary
      for a query or other statement. By default, session table data is held
      in memory. This can be changed with the <code class="literal">SET SESSION RESULT
      MEMORY ROWS</code> statement.</p>
</div>
</div>
<div class="section" title="Transactions and Concurrency Control">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="snc_tx_tx_cc"></a>Transactions and Concurrency Control</h2>
</div>
</div>
</div>
<p>HyperSQL 2 has been fully redesigned to support different
    transaction isolation models. It no longer supports the old 1.8.x model
    with "dirty read". Although it is perfectly possible to add an
    implementation of the transaction manager that supports the legacy model,
    we thought this is no longer necessary. The new system allows you to
    select the transaction isolation model while the engine is running. It
    also allows you to choose different isolation levels for different
    simultaneous sessions.</p>
<p>HyperSQL 2 supports three concurrency control models,
    two-phase-locking (2PL), which is the default, multiversion concurrency
    control (MVCC) and a hybrid model, which is 2PL plus multiversion rows.
    Within each model, it supports some of the 4 standard levels of
    transaction isolation: READ UNCOMMITTED, READ COMMITTED, REPEATABLE READ
    and SERIALIZABLE. The concurrency control model is a strategy that governs
    all the sessions and is set for the database, as opposed for individual
    sessions. The isolation level is a property of each SQL session, so
    different sessions can have different isolation levels. In the new
    implementation, all isolation levels avoid the "dirty read" phenomenon and
    do not read uncommitted changes made to rows by other transactions.</p>
<p>HyperSQL is fully multi threaded in all transaction models. Sessions
    continue to work simultaneously and can fully utilise multi-core
    processors.</p>
<p>To concurrency control model of a live database can be changed. The
    <code class="literal">SET DATABASE TRANSACTION CONTROL { LOCKS | MVLOCKS | MVCC
    }</code> can be used by a user with the DBA role.</p>
<div class="section" title="Two Phase Locking">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="snc_tx_2pl"></a>Two Phase Locking</h3>
</div>
</div>
</div>
<p>The two-phase locking model is the default mode. It is referred to
      by the keyword, LOCKS. In the 2PL model, each table that is read by a
      transaction is locked with a shared lock (read lock), and each table
      that is written to is locked with an exclusive lock (write lock). If two
      sessions read and modify different tables then both go through
      simultaneously. If one session tries to lock a table that has been
      locked by the other, if both locks are shared locks, it will go ahead.
      If either of the locks is an exclusive lock, the engine will put the
      session in wait until the other session commits or rolls back its
      transaction. In some cases the engine will invalidate the transaction of
      the current session, if the action would result in deadlock.</p>
<p>HyperSQL also supports explicit locking of a group of tables for
      the duration of the current transaction. Use of this command blocks
      access to the locked tables by other sessions and ensures the current
      session can complete the intended reads and writes on the locked
      tables.</p>
<p>If a table is read-only, it will not be locked by any
      transaction.</p>
<p>The READ UNCOMMITTED isolation level can be used in 2PL modes for
      read-only operations. It is the same as READ COMMITTED plus read
      only.</p>
<p>The READ COMMITTED isolation level is the default. It keeps write
      locks on tables until commit, but releases the read locks after each
      operation.</p>
<p>The REPEATABLE READ level is upgraded to SERIALIZABLE. These
      levels keep both read and write locks on tables until commit.</p>
<p>It is possible to perform some critical operations at the
      SERIALIZABLE level, while the rest of the operations are performed at
      the READ COMMITTED level.</p>
<p>Note: two phase locking refers to two periods in the life of a
      transaction. In the first period, locks are acquired, in the second
      period locks are released. No new lock is acquired after releasing a
      lock.</p>
</div>
<div class="section" title="Two Phase Locking with Snapshot Isolation">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="snc_tx_2pl_si"></a>Two Phase Locking with Snapshot Isolation</h3>
</div>
</div>
</div>
<p>This model is referred to as MVLOCKS. It works the same way as
      normal 2PL as far as updates are concerned.</p>
<p>SNAPSHOT ISOLATION is a multiversion concurrency strategy which
      uses the snapshot of the whole database at the time of the start of the
      transaction. In this model, read only transactions use SNAPSHOT
      ISOLATION. While other sessions are busy changing the database, the read
      only session sees a consistent view of the database and can access all
      the tables even when they are locked by other sessions for
      updates.</p>
<p>There are many applications for this mode of operation. In heavily
      updated data sets, this mode allows uninterrupted read access to the
      data.</p>
</div>
<div class="section" title="Lock Contention in 2PL">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="snc_tx_locks_2pl"></a>Lock Contention in 2PL</h3>
</div>
</div>
</div>
<p>When multiple connections are used to access the database, the
      transaction manager controls their activities. When each transaction
      performs only reads or writes on a single table, there is no contention.
      Each transaction waits until it can obtain a lock then performs the
      operation and commits. All contentions occur when transactions perform
      reads and writes on more than one table, or perform a read, followed by
      a write, on the same table.</p>
<p>For example, when sessions are working at the SERIALIZABLE level,
      when multiple sessions first read from a table in order to check if a
      row exists, then insert a row into the same table when it doesn't exist,
      there will be regular contention. Transaction A reads from the table,
      then does Transaction B. Now if either Transaction A or B attempts to
      insert a row, it will have to be terminated as the other transaction
      holds a shared lock on the table. If instead of two operations, a single
      MERGE statement is used to perform the read and write, no contention
      occurs because both locks are obtained at the same time.</p>
<p>Alternatively, there is the option of obtaining the necessary
      locks with an explicit LOCK TABLE statement. This statement should be
      executed before other statements and should include the names of all the
      tables and the locks needed. After this statement, all the other
      statements in the transaction can be executed and the transaction
      committed. The commit will remove all the locks.</p>
<p>HyperSQL detects deadlocks before attempting to execute a
      statement. When a lock is released after the completion of the
      statement, the first transaction that is waiting for the lock is allowed
      to continue.</p>
<p>HyperSQL is fully multi threaded. It therefore allows different
      transactions to execute concurrently so long as they are not waiting to
      lock the same table for write.</p>
</div>
<div class="section" title="Locks in SQL Routines and Triggers">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="snc_tx_locks_routines"></a>Locks in SQL Routines and Triggers</h3>
</div>
</div>
</div>
<p>In both LOCKS and MVLOCKS models, SQL routines (functions and
      procedures) and triggers obtain all the read and write locks at the
      beginning of the routine execution. SQL statements contained in the
      routine or trigger are all executed without deadlock as all the locks
      have already been obtained. At the end of execution of the routine or
      trigger, read locks are released if the session isolation level is READ
      COMMITTED.</p>
</div>
<div class="section" title="MVCC">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="snc_tx_mvcc"></a>MVCC</h3>
</div>
</div>
</div>
<p>In the MVCC model, there are no shared, read locks. Exclusive
      locks are used on individual rows, but their use is different.
      Transactions can read and modify the same table simultaneously,
      generally without waiting for other transactions. The SQL Standard
      isolation levels are used by the user's application, but these isolation
      levels are translated to the MVCC isolation levels READ CONSISTENCY or
      SNAPSHOT ISOLATION.</p>
<p>When transactions are running at READ COMMITTED level, no conflict
      will normally occur. If a transaction that runs at this level wants to
      modify a row that has been modified by another uncommitted transaction,
      then the engine puts the transaction in wait, until the other
      transaction has committed. The transaction then continues automatically.
      This isolation level is called READ CONSISTENCY.</p>
<p>Deadlock is completely avoided. In theory conflict is possible if
      each transaction is waiting for a different row modified by the other
      transaction. In this case, one of the transactions is immediately
      terminated (rolled back) unless the setting has been changed with the
      <code class="literal">&lt;set database transaction rollback on conflict
      statement&gt;</code>. When this setting is changed to FALSE, the
      session that avoided executing the deadlock-causing statement returns an
      error, but without rolling back the previous actions. This will cause
      the other transaction to wait for the current transaction. The property
      should not be changed unless the application can quickly perform an
      alternative statement to continue or roll back the transaction. This
      allows maximum flexibility and compatibility with other database engines
      which do not roll back the transaction upon deadlock.</p>
<p>When transactions are running in REPEATABLE READ or SERIALIZABLE
      isolation levels, conflict is more likely to happen. There is no
      difference in operation between these two isolation levels. This
      isolation level is called SNAPSHOT ISOLATION.</p>
<p>In this mode, when the duration of two transactions overlaps, if
      one of the transactions has modified a row and the second transaction
      wants to modify the same row, the action of the second transaction will
      fail. The engine will invalidate the second transaction and roll back
      all its changes. If the setting is changed to false with the
      <code class="literal">&lt;set database transaction rollback on conflict
      statement&gt;</code>, then the second transaction will just return an
      error without rolling back. The application must perform an alternative
      statement to continue or roll back the transaction.</p>
<p>In the MVCC model, READ UNCOMMITTED is promoted to READ COMMITTED,
      as the new architecture is based on multi-version rows for uncommitted
      data and more than one version may exist for some rows.</p>
<p>With MVCC, when a transaction only reads data, then it will go
      ahead and complete regardless of what other transactions may do. This
      does not depend on the transaction being read-only or the isolation
      modes.</p>
</div>
<div class="section" title="Choosing the Transaction Model">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="snc_tx_choosing"></a>Choosing the Transaction Model</h3>
</div>
</div>
</div>
<p>The SQL Standard defines the isolation levels as modes of
      operation that avoid the three unwanted phenomena, "dirty read", "fuzzy
      read" and "phantom row". The "dirty read" phenomenon occurs when a
      session can read a row that has been changed by another session. The
      "fuzzy read" phenomenon occurs when a row that was read by a session is
      modified by another session, then the first session reads the row again.
      The "phantom row" phenomenon occurs when a session performs an operation
      that affects several rows, for example, counts the rows or modifies them
      using a search condition, then another session adds one or more rows
      that fulfil the same search condition, then the first session performs
      an operation that relies on the results of its last operation. According
      to the Standard, the SERIALIZABLE isolation level avoids all three
      phenomena and also ensures that all the changes performed during a
      transaction can be considered as a series of uninterrupted changes to
      the database without any other transaction changing the database at all
      for the duration of these actions. The changes made by other
      transactions are considered to occur before the SERIALIZABLE transaction
      starts, or after it ends. The READ COMMITTED level avoids "dirty read"
      only, while the REPEATABLE READ level avoids "dirty read" and "fuzzy
      read", but not "phantom row".</p>
<p>The Standard allows the engine to return a higher isolation level
      than requested by the application. HyperSQL promotes a READ UNCOMMITTED
      request to READ COMMITTED and promotes a REPEATABLE READ request to
      SERIALIZABLE.</p>
<p>The MVCC model is not covered directly by the Standard. Research
      has established that the READ CONSISTENCY level fulfils the requirements
      of (and is stronger than) the READ COMMITTED level. The SNAPSHOT
      ISOLATION level is stronger than the READ CONSISTENCY level. It avoids
      the three anomalies defined by the Standard, and is therefore stronger
      than the REPEATABLE READ level as defined by the Standard. When
      operating with the MVCC model, HyperSQL treats a REPEATABLE READ or
      SERIALIZABLE setting for a transaction as SNAPSHOT ISOLATION.</p>
<p>All modes can be used with as many simultaneous connections as
      required. The default 2PL model is fine for applications with a single
      connection, or applications that do not access the same tables heavily
      for writes. With multiple simultaneous connections, MVCC can be used for
      most applications. Both READ CONSISTENCY and SNAPSHOT ISOLATION levels
      are stronger than the corresponding READ COMMITTED level in the 2PL
      mode. Some applications require SERIALIZABLE transactions for at least
      some of their operations. For these applications, one of the 2PL modes
      can be used. It is possible to switch the concurrency model while the
      database is operational. Therefore, the model can be changed for the
      duration of some special operations, such as synchronization with
      another data source.</p>
<p>All concurrency models are very fast in operation. When data
      change operations are mainly on the same tables, the MVCC model may be
      faster, especially with multi-core processors.</p>
</div>
<div class="section" title="Schema and Database Change">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="snc_tx_schema_change"></a>Schema and Database Change</h3>
</div>
</div>
</div>
<p>There are a few SQL statements that must access a consistent state
      of the database during their executions. These statements, which include
      CHECKPOINT and BACKUP, put an exclusive lock on all the tables of the
      database when they start.</p>
<p>Some schema manipulation statements put an exclusive lock on one
      or more tables. For example changing the columns of a table locks the
      table exclusively.</p>
<p>In the MVCC model, all statements that need an exclusive lock on
      one or more tables, put an exclusive lock on the database catalog until
      they complete.</p>
<p>The effect of these exclusive locks is similar to the execution of
      data manipulation statements with write locks. The session that is about
      to execute the schema change statement waits until no other session is
      holding a lock on any of the objects. At this point it starts its
      operation and locks the objects to prevents any other session from
      accessing the locked objects. As soon as the operation is complete, the
      locks are all removed.</p>
</div>
<div class="section" title="Simultaneous Access to Tables">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="snc_tx_access_tables"></a>Simultaneous Access to Tables</h3>
</div>
</div>
</div>
<p>It was mentioned that there is no limit on the number of sessions
      that can access the tables and all sessions work simultaneously in multi
      threaded execution. However there are internal resources that are
      shared. Simultaneous access to these resources can reduce the overall
      efficiency of the system. MEMORY and TEXT tables do not share resources
      and do not block multi threaded access. With CACHED tables, each row
      change operation blocks the file and its cache momentarily until the
      operation is finished. This is done separately for each row, therefore a
      multi-row INSERT, UPDATE, or DELETE statement will allow other sessions
      to access the file during its execution. With CACHED tables, SELECT
      operations do not block each other, but selecting from different tables
      and different parts of a large table causes the row cache to be updated
      frequently and will reduce overall performance.</p>
<p>The new access pattern is the opposite of the access pattern of
      version 1.8.x. In the old version, even when 20 sessions are actively
      reading and writing, only a single session at a time performs an SQL
      statement completely, before the next session is allowed access. In the
      new version, while a session is performing a SELECT statement and
      reading rows of a CACHED table to build a result set, another session
      may perform an UPDATE statement that reads and writes rows of the same
      table. The two operations are performed without any conflict, but the
      row cache is updated more frequently than when one operation is
      performed after the other operation has finished.</p>
</div>
<div class="section" title="Viewing Sessions">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="snc_viewing_sessions"></a>Viewing Sessions</h3>
</div>
</div>
</div>
<p>As HyperSQL is multithreaded, you can view the current sessions
      and their state from any admin session. The
      <code class="literal">INFORMATION_SCHEMA.SYSTEM_SESSIONS</code> table contains the
      list of open sessions, their unique ids and the statement currently
      executed or waiting to be executed by each session. For each session, it
      displays the list of sessions that are waiting for it to commit, or the
      session that this session is waiting for.</p>
</div>
</div>
<div class="section" title="Session and Transaction Control Statements">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="snc_statements"></a>Session and Transaction Control Statements</h2>
</div>
</div>
</div>
<a name="N10A26" class="indexterm"></a>
<p>
<span class="bold"><strong>ALTER SESSION</strong></span>
</p>
<p>
<span class="emphasis"><em>alter session statement</em></span>
</p>
<p>
<code class="literal">&lt;alter session statement&gt; ::= ALTER SESSION
    &lt;numeric literal&gt; { CLOSE | RELEASE }</code>
</p>
<p>
<code class="literal">&lt;alter current session statement&gt; ::= ALTER
    SESSION RESET { ALL | RESULT SETS | TABLE DATA }</code>
</p>
<p>The &lt;alter session statement&gt; is used by an administrator
    to close another session or to release the transaction in another session.
    When a session is released, its current transaction is terminated with a
    failure. The session remains open. This statement is different from the
    other statements discussed in this chapter as it is not used for changing
    the settings of the current session.</p>
<p>The session ID is used as a <code class="literal">&lt;numeric
    literal&gt;</code> in this statement. The administrator can use the
    <code class="literal">INFORMATION_SCHEMA.SYSTEM_SESSIONS</code> table to find the
    session IDs of other sessions.</p>
<p>The &lt;alter current session statement&gt; is used to clear and
    reset different states of the current session. When ALL is specified, the
    current transaction is rolled back, the session settings such as time
    zone, current schema etc. are restored to their original state at the time
    the session was opened and all open result sets are closed and temporary
    tables cleared. When RESULT SETS is specified, all currently open result
    sets are closed and the resources are released. When TABLE DATA is
    specified, the data in all temporary tables is cleared.</p>
<a name="N10A44" class="indexterm"></a>
<p>
<span class="bold"><strong>SET AUTOCOMMIT</strong></span>
</p>
<p>
<span class="emphasis"><em>set autocommit command</em></span>
</p>
<p>
<code class="literal">&lt;set autocommit statement&gt; ::= SET AUTOCOMMIT {
    TRUE | FALSE }</code>
</p>
<p>When an SQL session is started by creating a JDBC connection, it
    is in AUTOCOMMIT mode. In this mode, after each SQL statement a COMMIT is
    performed automatically. This statement changes the mode. It is equivalent
    to using the <code class="methodname">setAutoCommit( boolean autoCommit)</code>
    method of the JDBC <code class="classname">Connection</code> object.</p>
<a name="N10A5B" class="indexterm"></a>
<p>
<span class="bold"><strong>START TRANSACTION</strong></span>
</p>
<p>
<span class="emphasis"><em>start transaction statement</em></span>
</p>
<p>
<code class="literal">&lt;start transaction statement&gt; ::= START
    TRANSACTION [ &lt;transaction characteristics&gt; ]</code>
</p>
<p>Start an SQL transaction and set its characteristics. All
    transactional SQL statements start a transaction automatically, therefore
    using this statement is not necessary. If the statement is called in the
    middle of a transaction, an exception is thrown.</p>
<a name="N10A6C" class="indexterm"></a>
<p>
<span class="bold"><strong>SET TRANSACTION</strong></span>
</p>
<p>
<span class="emphasis"><em>set next transaction
    characteristics</em></span>
</p>
<p>
<code class="literal">&lt;set transaction statement&gt; ::= SET [ LOCAL ]
    TRANSACTION &lt;transaction characteristics&gt;</code>
</p>
<p>Set the characteristics of the next transaction in the current
    session. This statement has an effect only on the next transactions and
    has no effect on the future transactions after the next.</p>
<a name="N10A7D" class="indexterm"></a>
<p>
<span class="bold"><strong>transaction
    characteristics</strong></span>
</p>
<p>
<span class="emphasis"><em>transaction characteristics</em></span>
</p>
<p>
<code class="literal">&lt;transaction characteristics&gt; ::= [
    &lt;transaction mode&gt; [ { &lt;comma&gt; &lt;transaction mode&gt; }... ]
    ]</code>
</p>
<p>
<code class="literal">&lt;transaction mode&gt; ::= &lt;isolation level&gt; |
    &lt;transaction access mode&gt; | &lt;diagnostics
    size&gt;</code>
</p>
<p>
<code class="literal">&lt;transaction access mode&gt; ::= READ ONLY | READ
    WRITE</code>
</p>
<p>
<code class="literal">&lt;isolation level&gt; ::= ISOLATION LEVEL &lt;level of
    isolation&gt;</code>
</p>
<p>
<code class="literal">&lt;level of isolation&gt; ::= READ UNCOMMITTED | READ
    COMMITTED | REPEATABLE READ | SERIALIZABLE</code>
</p>
<p>
<code class="literal">&lt;diagnostics size&gt; ::= DIAGNOSTICS SIZE &lt;number
    of conditions&gt;</code>
</p>
<p>
<code class="literal">&lt;number of conditions&gt; ::= &lt;simple value
    specification&gt;</code>
</p>
<p>Specify transaction characteristics.</p>
<div class="example">
<a name="N10AA0"></a>
<p class="title">
<b>Example&nbsp;3.3.&nbsp;Setting Transaction Characteristics</b>
</p>
<div class="example-contents">
<pre class="screen"> SET TRANSACTION READ ONLY
 SET TRANSACTION ISOLATION LEVEL SERIALIZABLE
 SET TRANSACTION READ WRITE, ISOLATION LEVEL READ COMMITTED
</pre>
</div>
</div>
<br class="example-break">
<a name="N10AA5" class="indexterm"></a>
<p>
<span class="bold"><strong>SET CONSTRAINTS</strong></span>
</p>
<p>
<span class="emphasis"><em>set constraints mode statement</em></span>
</p>
<p>
<code class="literal">&lt;set constraints mode statement&gt; ::= SET
    CONSTRAINTS &lt;constraint name list&gt; { DEFERRED | IMMEDIATE
    }</code>
</p>
<p>
<code class="literal">&lt;constraint name list&gt; ::= ALL | &lt;constraint
    name&gt; [ { &lt;comma&gt; &lt;constraint name&gt; }...
    ]</code>
</p>
<p>If the statement is issued during a transaction, it applies to
    the rest of the current transaction. If the statement is issued when a
    transaction is not active then it applies only to the next transaction in
    the current session. HyperSQL does not yet support this feature.</p>
<a name="N10AB9" class="indexterm"></a>
<p>
<span class="bold"><strong>LOCK TABLE</strong></span>
</p>
<p>
<span class="emphasis"><em>lock table statement</em></span>
</p>
<p>
<code class="literal">&lt;lock table statement&gt; ::= LOCK TABLE &lt;table
    name&gt; { READ | WRITE} [, &lt;table name&gt; { READ | WRITE}
    ...]}</code>
</p>
<p>In some circumstances, where multiple simultaneous transactions
    are in progress, it may be necessary to ensure a transaction consisting of
    several statements is completed, without being terminated due to possible
    deadlock. When this statement is executed, it waits until it can obtain
    all the listed locks, then returns. If obtaining the locks would result in
    a deadlock an error is raised. The SQL statements following this
    statements use the locks already obtained (and obtain new locks if
    necessary) and can proceed without waiting. All the locks are released
    when a COMMIT or ROLLBACK statement is issued.</p>
<p>When the isolation level of a session is READ COMMITTED, read
    locks are released immediately after the execution of the statement,
    therefore you should use only WRITE locks in this mode. Alternatively, you
    can switch to the SERIALIZABLE isolation mode before locking the tables
    for the specific transaction that needs to finish consistently and without
    a deadlock. It is best to execute this statement at the beginning of the
    transaction with the complete list of required read and write
    locks.</p>
<p>Currently, this command does not have any effect when the
    database transaction control model is MVCC.</p>
<div class="example">
<a name="N10ACE"></a>
<p class="title">
<b>Example&nbsp;3.4.&nbsp;Locking Tables</b>
</p>
<div class="example-contents">
<pre class="screen"> LOCK TABLE table_a WRITE, table_b READ</pre>
</div>
</div>
<br class="example-break">
<a name="N10AD3" class="indexterm"></a>
<p>
<span class="bold"><strong>SAVEPOINT</strong></span>
</p>
<p>
<span class="emphasis"><em>savepoint statement</em></span>
</p>
<p>
<code class="literal">&lt;savepoint statement&gt; ::= SAVEPOINT &lt;savepoint
    specifier&gt;</code>
</p>
<p>
<code class="literal">&lt;savepoint specifier&gt; ::= &lt;savepoint
    name&gt;</code>
</p>
<p>Establish a savepoint. This command is used during an SQL
    transaction. It establishes a milestone for the current transaction. The
    SAVEPOINT can be used at a later point in the transaction to rollback the
    transaction to the milestone.</p>
<a name="N10AE7" class="indexterm"></a>
<p>
<span class="bold"><strong>RELEASE SAVEPOINT</strong></span>
</p>
<p>
<span class="emphasis"><em>release savepoint statement</em></span>
</p>
<p>
<code class="literal">&lt;release savepoint statement&gt; ::= RELEASE
    SAVEPOINT &lt;savepoint specifier&gt;</code>
</p>
<p>Destroy a savepoint. This command is rarely used as it is not
    very useful. It removes a SAVEPOINT that has already been
    defined.</p>
<a name="N10AF8" class="indexterm"></a>
<p>
<span class="bold"><strong>COMMIT</strong></span>
</p>
<p>
<span class="emphasis"><em>commit statement</em></span>
</p>
<p>
<code class="literal">&lt;commit statement&gt; ::= COMMIT [ WORK ] [ AND [ NO
    ] CHAIN ]</code>
</p>
<p>Terminate the current SQL-transaction with commit. This make all
    the changes to the database permanent.</p>
<a name="N10B09" class="indexterm"></a>
<p>
<span class="bold"><strong>ROLLBACK</strong></span>
</p>
<p>
<span class="emphasis"><em>rollback statement</em></span>
</p>
<p>
<code class="literal">&lt;rollback statement&gt; ::= ROLLBACK [ WORK ] [ AND [
    NO ] CHAIN ]</code>
</p>
<p>Rollback the current SQL transaction and terminate it. The
    statement rolls back all the actions performed during the transaction. If
    NO CHAIN is specified, a new SQL transaction is started just after the
    rollback. The new transaction inherits the properties of the old
    transaction.</p>
<a name="N10B1A" class="indexterm"></a>
<p>
<span class="bold"><strong>ROLLBACK TO SAVEPOINT</strong></span>
</p>
<p>
<span class="emphasis"><em>rollback statement</em></span>
</p>
<p>
<code class="literal">&lt;rollback statement&gt; ::= ROLLBACK [ WORK ] TO
    SAVEPOINT &lt;savepoint specifier&gt;</code>
</p>
<p>Rollback part of the current SQL transaction and continue the
    transaction. The statement rolls back all the actions performed after the
    specified SAVEPOINT was created. The same effect can be achieved with the
    <code class="literal">rollback( Savepoint savepoint)</code> method of the JDBC
    <code class="classname">Connection</code> object.</p>
<div class="example">
<a name="N10B31"></a>
<p class="title">
<b>Example&nbsp;3.5.&nbsp;Rollback</b>
</p>
<div class="example-contents">
<pre class="screen"> -- perform some inserts, deletes, etc.
 SAVEPOINT A
 -- perform some inserts, deletes, selects etc.
 ROLLBACK WORK TO SAVEPOINT A
 -- all the work after the declaration of SAVEPOINT A is rolled back
</pre>
</div>
</div>
<br class="example-break">
<a name="N10B37" class="indexterm"></a>
<p>
<span class="bold"><strong>DISCONNECT</strong></span>
</p>
<p>
<span class="emphasis"><em>disconnect statement</em></span>
</p>
<p>
<code class="literal">&lt;disconnect statement&gt; ::=
    DISCONNECT</code>
</p>
<p>Terminate the current SQL session. Closing a JDBC connection has
    the same effect as this command.</p>
<a name="N10B49" class="indexterm"></a>
<p>
<span class="bold"><strong>SET SESSION
    CHARACTERISTICS</strong></span>
</p>
<p>
<span class="emphasis"><em>set session characteristics
    statement</em></span>
</p>
<p>
<code class="literal">&lt;set session characteristics statement&gt; ::= SET
    SESSION CHARACTERISTICS AS &lt;session characteristic
    list&gt;</code>
</p>
<p>
<code class="literal">&lt;session characteristic list&gt; ::= &lt;session
    characteristic&gt; [ { &lt;comma&gt; &lt;session characteristic&gt; }...
    ]</code>
</p>
<p>
<code class="literal">&lt;session characteristic&gt; ::= &lt;session
    transaction characteristics&gt;</code>
</p>
<p>
<code class="literal">&lt;session transaction characteristics&gt; ::=
    TRANSACTION &lt;transaction mode&gt; [ { &lt;comma&gt; &lt;transaction
    mode&gt; }... ]</code>
</p>
<p>Set one or more characteristics for the current SQL-session. This
    command is used to set the transaction mode for the session. This endures
    for all transactions until the session is closed or the next use of this
    command. The current read-only mode can be accessed with the ISREADONLY()
    function.</p>
<div class="example">
<a name="N10B63"></a>
<p class="title">
<b>Example&nbsp;3.6.&nbsp;Setting Session Characteristics</b>
</p>
<div class="example-contents">
<pre class="screen"> SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY
 SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL SERIALIZABLE
 SET SESSION CHARACTERISTICS AS TRANSACTION READ WRITE, ISOLATION LEVEL READ COMMITTED
</pre>
</div>
</div>
<br class="example-break">
<a name="N10B68" class="indexterm"></a>
<p>
<span class="bold"><strong>SET SESSION
    AUTHORIZATION</strong></span>
</p>
<p>
<span class="emphasis"><em>set session user identifier
    statement</em></span>
</p>
<p>
<code class="literal">&lt;set session user identifier statement&gt; ::= SET
    SESSION AUTHORIZATION &lt;value specification&gt;</code>
</p>
<p>Set the SQL-session user identifier. This statement changes the
    current user. The user that executes this command must have the
    CHANGE_AUTHORIZATION role, or the DBA role. After this statement is
    executed, all SQL statements are executed with the privileges of the new
    user. The current authorisation can be accessed with the CURRENT_USER and
    SESSION_USER functions.</p>
<div class="example">
<a name="N10B79"></a>
<p class="title">
<b>Example&nbsp;3.7.&nbsp;Setting Session Authorization</b>
</p>
<div class="example-contents">
<pre class="screen"> SET SESSION AUTHORIZATION 'FELIX'
 SET SESSION AUTHORIZATION SESSION_USER
</pre>
</div>
</div>
<br class="example-break">
<a name="N10B7E" class="indexterm"></a>
<p>
<span class="bold"><strong>SET ROLE</strong></span>
</p>
<p>
<span class="emphasis"><em>set role statement</em></span>
</p>
<p>
<code class="literal">&lt;set role statement&gt; ::= SET ROLE &lt;role
    specification&gt;</code>
</p>
<p>
<code class="literal">&lt;role specification&gt; ::= &lt;value
    specification&gt; | NONE</code>
</p>
<p>Set the SQL-session role name and the current role name for the
    current SQL-session context. The user that executes this command must have
    the specified role. If NONE is specified, then the previous CURRENT_ROLE
    is eliminated. The effect of this lasts for the lifetime of the session.
    The current role can be accessed with the CURRENT_ROLE function.</p>
<a name="N10B92" class="indexterm"></a>
<p>
<span class="bold"><strong>SET TIME ZONE</strong></span>
</p>
<p>
<span class="emphasis"><em>set local time zone statement</em></span>
</p>
<p>
<code class="literal">&lt;set local time zone statement&gt; ::= SET TIME ZONE
    &lt;set time zone value&gt;</code>
</p>
<p>
<code class="literal">&lt;set time zone value&gt; ::= &lt;interval value
    expression&gt; | LOCAL</code>
</p>
<p>Set the current default time zone displacement for the current
    SQL-session. When the session starts, the time zone displacement is set to
    the time zone of the client. This command changes the time zone
    displacement. The effect of this lasts for the lifetime of the session. If
    LOCAL is specified, the time zone displacement reverts to the local time
    zone of the session.</p>
<div class="example">
<a name="N10BA6"></a>
<p class="title">
<b>Example&nbsp;3.8.&nbsp;Setting Session Time Zone</b>
</p>
<div class="example-contents">
<pre class="screen"> SET TIME ZONE LOCAL
 SET TIME ZONE INTERVAL '+6:00' HOUR TO MINUTE
</pre>
</div>
</div>
<br class="example-break">
<a name="N10BAB" class="indexterm"></a>
<p>
<span class="bold"><strong>SET CATALOG</strong></span>
</p>
<p>
<span class="emphasis"><em>set catalog statement</em></span>
</p>
<p>
<code class="literal">&lt;set catalog statement&gt; ::= SET &lt;catalog name
    characteristic&gt;</code>
</p>
<p>
<code class="literal">&lt;catalog name characteristic&gt; ::= CATALOG
    &lt;value specification&gt;</code>
</p>
<p>Set the default schema name for unqualified names used in SQL
    statements that are prepared or executed directly in the current sessions.
    As there is only one catalog in the database, only the name of this
    catalog can be used. The current catalog can be accessed with the
    CURRENT_CATALOG function.</p>
<a name="N10BBF" class="indexterm"></a>
<p>
<span class="bold"><strong>SET SCHEMA</strong></span>
</p>
<p>
<span class="emphasis"><em>set schema statement</em></span>
</p>
<p>
<code class="literal">&lt;set schema statement&gt; ::= SET &lt;schema name
    characteristic&gt;</code>
</p>
<p>
<code class="literal">&lt;schema name characteristic&gt; ::= SCHEMA &lt;value
    specification&gt; | &lt;schema name&gt;</code>
</p>
<p>Set the default schema name for unqualified names used in SQL
    statements that are prepared or executed directly in the current sessions.
    The effect of this lasts for the lifetime of the session. The SQL Standard
    form requires the schema name as a single-quoted string. HyperSQL also
    allows the use of the identifier for the schema. The current schema can be
    accessed with the CURRENT_SCHEMA function.</p>
<a name="N10BD3" class="indexterm"></a>
<p>
<span class="bold"><strong>SET PATH</strong></span>
</p>
<p>
<span class="emphasis"><em>set path statement</em></span>
</p>
<p>
<code class="literal">&lt;set path statement&gt; ::= SET &lt;SQL-path
    characteristic&gt;</code>
</p>
<p>
<code class="literal">&lt;SQL-path characteristic&gt; ::= PATH &lt;value
    specification&gt;</code>
</p>
<p>Set the SQL-path used to determine the subject routine of routine
    invocations with unqualified routine names used in SQL statements that are
    prepared or executed directly in the current sessions. The effect of this
    lasts for the lifetime of the session.</p>
<a name="N10BE7" class="indexterm"></a>
<p>
<span class="bold"><strong>SET MAXROWS</strong></span>
</p>
<p>
<span class="emphasis"><em>set max rows statement</em></span>
</p>
<p>
<code class="literal">&lt;set max rows statement&gt; ::= SET MAXROWS
    &lt;unsigned integer literal&gt;</code>
</p>
<p>The normal operation of the session has no limit on the number of
    rows returned from a SELECT statement. This command set the maximum number
    of rows of the result returned by executing queries.</p>
<p>This statement has a similar effect to the
    <code class="methodname">setMaxRows(int max)</code> method of the JDBC
    <code class="classname">Statement</code> interface, but it affects the results
    returned from the next statement execution only. After the execution of
    the next statement, the MAXROWS limit is removed.</p>
<p>Only zero or positive values can be used with this command. The
    value overrides any value specified with <code class="methodname">setMaxRows(int
    max)</code> method of a JDBC statement. The statement <code class="literal">SET
    MAXROWS 0</code> means no limit.</p>
<p>It is possible to limit the number of rows returned from SELECT
    statements with the FETCH &lt;n&gt; ROWS ONLY, or its alternative, LIMIT
    &lt;n&gt;. Therefore this command is not recommended for general use. The
    only legitimate use of this command is for checking and testing queries
    that may return very large numbers of rows.</p>
<a name="N10C0A" class="indexterm"></a>
<p>
<span class="bold"><strong>SET SESSION RESULT MEMORY
    ROWS</strong></span>
</p>
<p>
<span class="emphasis"><em>set session result memory rows
    statement</em></span>
</p>
<p>
<code class="literal">&lt;set session result memory rows statement&gt; ::= SET
    SESSION RESULT MEMORY ROWS &lt;unsigned integer
    literal&gt;</code>
</p>
<p>By default the session uses memory to build result sets, subquery
    results and temporary tables. This command sets the maximum number of rows
    of the result (and temporary tables) that should be kept in memory. If the
    row count of the result or temporary table exceeds the setting, the result
    is stored on disk. The default is 0, meaning all result sets are held in
    memory.</p>
<p>This statement applies to the current session only. The general
    database setting is:</p>
<p>
<code class="literal">SET DATABASE DEFAULT RESULT MEMORY ROWS &lt;unsigned
    integer literal&gt;</code>
</p>
<a name="N10C20" class="indexterm"></a>
<p>
<span class="bold"><strong>SET IGNORECASE</strong></span>
</p>
<p>
<span class="emphasis"><em>set ignore case statement</em></span>
</p>
<p>
<code class="literal">&lt;set ignore case statement&gt; ::= SET IGNORECASE {
    TRUE | FALSE }</code>
</p>
<p>This is a legacy method for creating case-insensitive columns.
    Still supported but not recommended for use.</p>
<p>Sets the type used for new VARCHAR table columns. By default,
    character columns in new databases are case-sensitive. If <code class="literal">SET
    IGNORECASE TRUE</code> is used, all VARCHAR columns in new tables are
    set to use a collation that converts strings to uppercase for comparison.
    In the latest versions of HyperSQL you can specify the collations for the
    database and for each column and have some columns case-sensitive and some
    not, even in the same table. The collation's strength is used to force
    case-insensitive comparison. Collations are discussed in the <a class="link" href="#databaseobjects-chapt" title="Chapter&nbsp;4.&nbsp;Schemas and Database Objects">Schemas and Database Objects</a> chapter.</p>
<p>This statement must be switched before creating tables. Existing
    tables and their data are not affected.</p>
</div>
</div>
<div class="chapter" title="Chapter&nbsp;4.&nbsp;Schemas and Database Objects">
<div class="titlepage">
<div>
<div>
<h2 class="title">
<a name="databaseobjects-chapt"></a>Chapter&nbsp;4.&nbsp;Schemas and Database Objects</h2>
</div>
<div>
<div class="authorgroup">
<div class="author">
<h3 class="author">
<span class="firstname">Fred</span> <span class="surname">Toussi</span>
</h3>
<div class="affiliation">
<span class="orgname">The HSQL Development Group<br>
</span>
</div>
</div>
</div>
</div>
<div>
<p class="releaseinfo">$Revision: 5243 $</p>
</div>
<div>
<div class="legalnotice" title="Legal Notice">
<a name="N10C61"></a>
<p>Copyright 2009-2013 Fred Toussi. Permission is granted to
      distribute this document without any alteration under the terms of the
      HSQLDB license. Additional permission is granted to the HSQL Development
      Group to distribute this document with or without alterations under the
      terms of the HSQLDB license.</p>
</div>
</div>
<div>
<p class="pubdate">2014-02-13 18:21:41-0500</p>
</div>
</div>
</div>
<div class="toc">
<p>
<b>Table of Contents</b>
</p>
<dl>
<dt>
<span class="section"><a href="#dbc_overview">Overview</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_schemas_schema_objects">Schemas and Schema Objects</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#dbc_names_references">Names and References</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_character_sets">Character Sets</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_collations">Collations</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_distinct_types">Distinct Types</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_domains_info_schema">Domains</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_number_sequence">Number Sequences</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_tables">Tables</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_views">Views</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_constraints">Constraints</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_assertions">Assertions</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_triggers">Triggers</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_routines">Routines</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_indexes">Indexes</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#dbc_schema_def_statements">Statements for Schema Definition and Manipulation</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#dbc_common_elements">Common Elements and Statements</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_renaming">Renaming Objects</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_commenting">Commenting Objects</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_schema_creation">Schema Creation</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_table_creation">Table Creation</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_table_manupulation">Table Manipulation</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_view_creation">View Creation and Manipulation</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_domain_creation">Domain Creation and Manipulation</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_trigger_creation">Trigger Creation</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_routine_creation">Routine Creation</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_sequence_creation">Sequence Creation</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_procedure_satement">SQL Procedure Statement</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_other_object_creation">Other Schema Object Creation</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#dbc_information_schema">The Information Schema</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#dbc_char_sets_info_schema">Predefined Character Sets, Collations and Domains</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_views_info_schema">Views in INFORMATION SCHEMA</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_visibility_info_schema">Visibility of Information</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_name_info_schema">Name Information</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_data_type_info_schema">Data Type Information</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_product_info_schema">Product Information</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_operations_info_schema">Operations Information</a></span>
</dt>
<dt>
<span class="section"><a href="#dbc_standard_views_info_schema">SQL Standard Views</a></span>
</dt>
</dl>
</dd>
</dl>
</div>
<div class="section" title="Overview">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="dbc_overview"></a>Overview</h2>
</div>
</div>
</div>
<p>The persistent elements of an SQL environment are database objects.
    The database consists of catalogs plus authorizations.</p>
<p>A catalog contains schemas, while schemas contain the objects that
    contain data or govern the data.</p>
<p>Each catalog contains a special schema called INFORMATION_SCHEMA.
    This schema is read-only and contains some views and other schema objects.
    The views contain lists of all the database objects that exist within the
    catalog, plus all authorizations.</p>
<p>Each database object has a name. A name is an identifier and is
    unique within its name-space.</p>
</div>
<div class="section" title="Schemas and Schema Objects">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="dbc_schemas_schema_objects"></a>Schemas and Schema Objects</h2>
</div>
</div>
</div>
<p>In HyperSQL, there is only one catalog per database. The name of the
    catalog is PUBLIC. You can rename the catalog with the <code class="literal">ALTER
    CATALOG RENAME TO</code> statement. All schemas belong the this
    catalog. The catalog name has no relation to the file name of the
    database.</p>
<p>Each database has also an internal "unique" name which is
    automatically generated when the database is created. This name is used
    for event logging. You can also change this unique name.</p>
<p>Schema objects are database objects that contain data or govern or
    perform operations on data. By definition, each schema object belongs to a
    specific schema.</p>
<p>Schema objects can be divided into groups according to their
    characteristics.</p>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>Some kinds of schema objects can exist independently from other
        schema object. Other kinds can exist only as an element of another
        schema object. These dependent objects are automatically destroyed
        when the parent object is dropped.</p>
</li>
<li class="listitem">
<p>Separate name-spaces exists for different kinds of schema
        object. Some name-spaces are shared between two similar kinds of
        schema objects.</p>
</li>
<li class="listitem">
<p>There can be dependencies between various schema objects, as a
        schema object can include references to other schema objects. These
        references can cross schema boundaries. Interdependence and cross
        referencing between schema objects is allowed in some circumstances
        and disallowed in some others.</p>
</li>
<li class="listitem">
<p>Schema objects can be destroyed with the DROP statement. If
        dependent schema objects exist, a DROP statement will succeed only if
        it has a CASCADE clause. In this case, dependent objects are also
        destroyed in most cases. In some cases, such as dropping DOMAIN
        objects, the dependent objects are not destroyed, but modified to
        remove the dependency.</p>
</li>
</ul>
</div>
<p>A new HyperSQL catalog contains an empty schema called PUBLIC. By
    default, this schema is the initial schema when a new session is started.
    New schemas and schema objects can be defined and used in the PUBLIC
    schema, as well as any new schema that is created by the user. You can
    rename the PUBLIC schema.</p>
<p>HyperSQL allows all schemas to be dropped, except the schema that is
    the default initial schema for new sessions (by default, the PUBLIC
    schema). For this schema, a DROP SCHEMA ... CASCADE statement will succeed
    but will result in an empty schema, rather than no schema.</p>
<p>The statements for setting the initial schema for users are
    described in the <a class="link" href="#accesscontrol-chapt" title="Chapter&nbsp;6.&nbsp;Access Control">Statements for
    Authorization and Access Control</a> chapter.</p>
<div class="section" title="Names and References">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dbc_names_references"></a>Names and References</h3>
</div>
</div>
</div>
<p>The name of a schema object is an
      <code class="literal">&lt;identifier&gt;</code>. The name belongs to the
      name-space for the particular kind of schema object. The name is unique
      within its name-space. For example, each schema has a separate
      name-space for TRIGGER objects.</p>
<p>In addition to the name-spaces in the schema. Each table has a
      name-space for the names of its columns.</p>
<p>Because a schema object is always in a schema and a schema always
      in a catalog, it is possible, and sometimes necessary, to qualify the
      name of the schema object that is being referenced in an SQL statement.
      This is done by forming an &lt;<code class="literal">identifier chain&gt;</code>.
      In some contexts, only a simple <code class="literal">&lt;identifier&gt;</code>
      can be used and the <code class="literal">&lt;identifier chain&gt;</code> is
      prohibited. While in some other contexts, the use of
      <code class="literal">&lt;identifier chain&gt;</code> is optional. An identifier
      chain is formed by qualifying each object with the name of the object
      that owns its name-space. Therefore a column name is prefixed with a
      table name, a table name is prefixed with a schema name, and a schema
      name is prefixed with a catalog name. A fully qualified column name is
      in the form <code class="literal">&lt;catalog name&gt;.&lt;schema name&gt;.&lt;table
      name&gt;.&lt;column name&gt;</code>, likewise, a fully qualified
      sequence name is in the form <code class="literal">&lt;catalog name&gt;.&lt;schema
      name&gt;.&lt;sequence name&gt;</code>.</p>
<p>HyperSQL extends the SQL standard to allow renaming all database
      objects. The ALTER ... RENAME TO command has slightly different forms
      depending on the type of object. If an object is referenced in a VIEW or
      ROUTINE definition, it is not always possible to rename it.</p>
</div>
<div class="section" title="Character Sets">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dbc_character_sets"></a>Character Sets</h3>
</div>
</div>
</div>
<p>A CHARACTER SET is the whole or a subset of the UNICODE character
      set.</p>
<p>A character set name can only be a <code class="literal">&lt;regular
      identifier&gt;</code>. There is a separate name-space for character
      sets.</p>
<p>There are several predefined character sets. These character sets
      belong to INFORMATION_SCHEMA. However, when they are referenced in a
      statement, no schema prefix is necessary.</p>
<p>The following character sets, together with some others, have been
      specified by the SQL Standard:</p>
<p>SQL_TEXT, SQL_IDENTIFIER, SQL_CHARACTER</p>
<p>The SQL_CHARACTER consists of ASCII letters, digits and the
      symbols used in the SQL language. SQL_TEXT and SQL_IDENTIFIER are
      implementation defined. HyperSQL defines SQL_TEXT as the UNICODE
      character set and SQL_IDENTIFIER as the UNICODE character set minus the
      SQL language special characters.</p>
<p>SQL_TEXT consists of the full set of Unicode characters. These
      characters can be used in strings and clobs stored in the database. The
      character repertoire of HyperSQL is the UTF16 character set, which
      covers all possible character sets.</p>
<p>If a predefined character set is specified for a table column,
      then any string stored in the column must contain only characters from
      the specified character set. HyperSQL does not enforce the CHARACTER SET
      that is specified for a column and may accept any character string
      supported by SQL_TEXT.</p>
</div>
<div class="section" title="Collations">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dbc_collations"></a>Collations</h3>
</div>
</div>
</div>
<p>A COLLATION is the method used for ordering character strings in
      ordered sets and to determine equivalence of two character
      strings.</p>
<p>The system collation is called SQL_TEXT. This collation sorts
      according to the Unicode code of the characters, UNICODE_SIMPLE. The
      system collation is always used for INFORMATION_SCHEMA tables.</p>
<p>The default database collation is the same as the system
      collation. You can change this default, either with a language
      collation, or with the SQL_TEXT_UCC. This collation is a
      case-insensitive form of the UNICODE_SIMPLE collation.</p>
<p>Collations for a large number of languages are supported by
      HyperSQL. These collations belong to INFORMATION_SCHEMA. However, when
      they are referenced in a statement, there is no need for a schema
      prefix.</p>
<p>A different collation than the default collation can be specified
      for each table column that is defined as CHAR or VARCHAR.</p>
<p>A collation can also be used in an ORDER BY clause.</p>
<p>A collation can be used in the GROUP BY clause.</p>
<div class="informalexample">
<pre class="programlisting"> CREATE TABLE t (id INTEGER PRIMARY KEY, name VARCHAR(20) COLLATE "English")
 SELECT * FROM t ORDER BY name COLLATE "French"
 SELECT COUNT(*), name FROM t GROUP BY name COLLATE "English 0"
</pre>
</div>
<p>In the examples above, the collation for the column is already
      specified when it is defined. In the first SELECT statement, the column
      is sorted using the French collation. In the second SELECT, the
      <code class="literal">"English 0"</code> collation is used in the GROUP BY clause.
      This collation is case insensitive, so the same name with different uses
      of upper and lower case letters is considered the same and counted
      together.</p>
<p>The supported collations are named according to the language. You
      can see the list in the INFORMATION_SCHEMA.COLLATIONS view. You can use
      just the name in double quotes for the default form of the collation. If
      you add a strength between 0, 1, 2, 3, the case sensitivity and accent
      sensitivity changes. The value 0 indicates least sensitivity to
      differences. At this strength the collation is case-insensitive and
      ignores differences between accented letters. At strength 1, differences
      between accented letters are taken into account. At strength 2, both
      case and accent are significant. Finally 3 indicates additional
      sensitivity to different punctuation. A second parameter can also be
      used with values 0 or 1, to indicate how decomposition of accented
      characters for comparison is handled for languages that support such
      characters. See the Java and ICU (International Components for Unicode)
      collation documentation for more details on these values. For example,
      possible forms of the French collation are <code class="literal">"French"</code>,
      <code class="literal">"French 0"</code>, <code class="literal">"French 1"</code>, etc. and
      <code class="literal">"French 2 1"</code>, etc. When the collation is specified
      without strength, it seems the system defaults to strength 2, which is
      case and accent sensitive.</p>
<p>When a collation is not explicitly used in the CREATE TABLE
      statement for a column, then the database default collation is used for
      this column. If you change the database default collation afterwards,
      the new collation will be used.</p>
<p>With the older versions of HyperSQL the special type
      VARCHAR_IGNORECASE was used as the column type for case-insensitive
      comparison. Any column already defined as VARCHAR_IGNORECASE will be
      compared exactly as before. In version 2.3.0 and later, this form is
      represented by the addition of UCC after the collation name, for example
      "French UCC". You can still use the SET IGNORECASE TRUE statement in
      your session to force the UCC to be applied to the collation for the
      VARCHAR columns of new tables. UCC stands for Upper Case Comparison.
      Before comparing two strings, both are converted to uppercase using the
      current collation. This is exactly how VARCHAR_IGNORECASE worked.</p>
<p>It is recommended to use the default SQL_TEXT collation for your
      general CHAR or VARCHAR columns. For columns where a language collation
      is desirable, the choice should be made very carefully, because names
      that are very similar but only differ in the accents may be considered
      equal in searches.</p>
<p>When comparing two strings, HyperSQL 2 pads the shorter string
      with spaces in order to compare two strings of equal length. You can
      change the default database collation with one that does not pad the
      string with spaces before comparison. This method of comparison was used
      in versions older than 2.</p>
<p>User defined collations can be created based on existing
      collations to control the space padding. These collations are part of
      the current schema.</p>
<p>See the COLLATE keyword and SET DATABASE COLLATION statement in
      the <a class="link" href="#management-chapt" title="Chapter&nbsp;11.&nbsp;System Management">System Management</a> chapter. The PAD SPACE or NO PAD
      clause is used to control padding.</p>
<div class="important" title="Important" style="margin-left: 0.5in; margin-right: 0.5in;">
<table border="0" summary="Important">
<tr>
<td valign="top" align="center" rowspan="2" width="25"><img alt="[Important]" src="../images/db/important.png"></td><th align="left">Important</th>
</tr>
<tr>
<td valign="top" align="left">
<p>If you change the default collation of a database when there are
        tables containing data with CHAR or VARCHAR columns that are part of
        an index, a primary key or a unique constraint, you must execute
        SHUTDOWN COMPACT or SHUTDOWN SCRIPT after the change. If you do not do
        this, your queries and other statements will show erratic behaviour
        and may result in unrecoverable errors.</p>
</td>
</tr>
</table>
</div>
</div>
<div class="section" title="Distinct Types">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dbc_distinct_types"></a>Distinct Types</h3>
</div>
</div>
</div>
<p>A distinct, user-defined TYPE is simply based on a built-in type.
      A distinct TYPE is used in table definitions and in CAST
      statements.</p>
<p>Distinct types share a name-space with domains.</p>
</div>
<div class="section" title="Domains">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dbc_domains_info_schema"></a>Domains</h3>
</div>
</div>
</div>
<p>A DOMAIN is a user-defined type, simply based on a built-in type.
      A DOMAIN can have constraints that limit the values that the DOMAIN can
      represent. A DOMAIN can be used in table definitions and in CAST
      statements.</p>
<p>Distinct types share a name-space with domains.</p>
</div>
<div class="section" title="Number Sequences">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dbc_number_sequence"></a>Number Sequences</h3>
</div>
</div>
</div>
<p>A SEQUENCE object produces INTEGER values in sequence. The
      SEQUENCE can be referenced in special contexts only within certain SQL
      statements. For each row where the object is referenced, its value is
      incremented.</p>
<p>There is a separate name-space for SEQUENCE objects.</p>
<p>IDENTITY columns are columns of tables which have an internal,
      unnamed SEQUENCE object. HyperSQL also supports IDENTITY columns that
      use a named SEQUENCE object.</p>
<p>SEQUENCE objects and IDENTITY columns are supported fully
      according to the latest SQL 2008 Standard syntax.</p>
<p>
<span class="bold"><strong>Sequences</strong></span>
</p>
<p>The SQL:2008 syntax and usage is different from what is supported
      by many existing database engines. Sequences are created with the
      <code class="literal">CREATE SEQUENCE</code> command and their current value can
      be modified at any time with <code class="literal">ALTER SEQUENCE</code>. The next
      value for a sequence is retrieved with the <code class="literal">NEXT VALUE FOR
      &lt;name&gt;</code> expression. This expression can be used for
      inserting and updating table rows.</p>
<div class="example">
<a name="N10D36"></a>
<p class="title">
<b>Example&nbsp;4.1.&nbsp;inserting the next sequence value into a table row</b>
</p>
<div class="example-contents">
<pre class="programlisting"> INSERT INTO mytable VALUES 2, 'John', NEXT VALUE FOR mysequence</pre>
</div>
</div>
<br class="example-break">
<p>You can also use it in select statements. For example, if you want
      to number the returned rows of a SELECT in sequential order, you can
      use:</p>
<div class="example">
<a name="N10D3D"></a>
<p class="title">
<b>Example&nbsp;4.2.&nbsp;numbering returned rows of a SELECT in sequential order</b>
</p>
<div class="example-contents">
<pre class="programlisting"> SELECT NEXT VALUE FOR mysequence, col1, col2 FROM mytable WHERE ...</pre>
</div>
</div>
<br class="example-break">
<p>In version 2.0, the semantics of sequences is exactly as defined
      by SQL:2008. If you use the same sequence twice in the same row in an
      INSERT statement, you will get the same value as required by the
      Standard.</p>
<p>The correct way to use a sequence value is the NEXT VALUE FOR
      expression.</p>
<p>HyperSQL adds an extension to Standard SQL to return the last
      value returned by the NEXT VALUE FOR expression in the current session.
      After a statement containing NEXT VALUE FOR is executed, the value that
      was returned for NEXT VALUE FOR is available using the CURRENT VALUE FOR
      expression. In the example below, the NEXT VALUE FOR expression is used
      to insert a new row. The value that was returned by NEXT VALUE FOR is
      retrieved with the CURRENT VALUE FOR in the next insert statements to
      populate two new rows in a different table that has a parent child
      relationship with the first table. For example if the value 15 was
      returned by the sequence, the same value 15 is inserted in the three
      rows.</p>
<div class="example">
<a name="N10D49"></a>
<p class="title">
<b>Example&nbsp;4.3.&nbsp;using the last value of a sequence</b>
</p>
<div class="example-contents">
<pre class="programlisting"> INSERT INTO mytable VALUES 2, 'John', NEXT VALUE FOR mysequence
 INSERT INTO childtable VALUES 4, CURRENT VALUE FOR mysequence
 INSERT INTO childtable VALUES 5, CURRENT VALUE FOR mysequence</pre>
</div>
</div>
<p>
<br class="example-break">The INFORMATION_SCHEMA.SEQUENCES table contains the next
      value that will be returned from any of the defined sequences. The
      SEQUENCE_NAME column contains the name and the NEXT_VALUE column
      contains the next value to be returned. Note that this is only for
      getting information and you should not use it for accessing the next
      sequence value. When multiple sessions access the same sequence, the
      value returned from this table by one session could also be used by a
      different session, causing a sequence value to be used twice
      unintentionally.</p>
<p>
<span class="bold"><strong>Identity Auto-Increment
      Columns</strong></span>
</p>
<p>Each table can contain a single auto-increment column, known as
      the IDENTITY column. An IDENTITY column is a SMALLINT, INTEGER, BIGINT,
      DECIMAL or NUMERIC column with its value generated by a sequence
      generator.</p>
<p>In HyperSQL 2.0, an IDENTITY column is not by default treated as
      the primary key for the table (as a result, multi-column primary keys
      are possible with an IDENTITY column present). Use the SQL standard
      syntax for declaration of the IDENTITY column.</p>
<p>The SQL standard syntax is used, which allows the initial value
      and other options to be specified.</p>
<p>
<code class="literal">&lt;colname&gt; [ INTEGER | BIGINT | DECIMAL | NUMERIC ]
      GENERATED { BY DEFAULT | ALWAYS} AS IDENTITY [( &lt;options&gt;
      )]</code>
</p>
<div class="informalexample">
<pre class="programlisting"> /* this table has no primary key */
 CREATE TABLE vals (id INTEGER GENERATED BY DEFAULT AS IDENTITY, data VARBINARY(2000))
 
 /* in this table id becomes primary key because the old syntax is used - avoid this syntax */
 CREATE TABLE vals (id INTEGER IDENTITY, data VARBINARY(2000))

 /* use the standard syntax and explicity declare a primary key identity column */
 CREATE TABLE vals (id INTEGER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY, data VARBINARY(2000))
</pre>
</div>
<p>When you add a new row to such a table using an <code class="literal">INSERT
      INTO &lt;tablename&gt; ... </code>statement, you can use the DEFAULT
      keyword for the IDENTITY column, which results in an auto-generated
      value for the column.</p>
<p>The <code class="literal">IDENTITY() </code>function returns the last value
      inserted into any IDENTITY column by this session. Each session manages
      this function call separately and is not affected by inserts in other
      sessions. Use <code class="literal">CALL IDENTITY() </code>as an SQL statement to
      retrieve this value. If you want to use the value for a field in a child
      table, you can use <code class="literal">INSERT INTO &lt;childtable&gt; VALUES
      (...,IDENTITY(),...);</code>. Both types of call to<code class="literal">
      IDENTITY()</code> must be made before any additional update or insert
      statements are issued by the session.</p>
<p>In triggers and routines, the value returned by the
      <code class="literal">IDENTITY()</code> function is correct for the given context.
      For example, if a call to a stored procedure inserts a row into a table,
      causing a new identity value to be generated, a call to
      <code class="literal">IDENTITY()</code> inside the procedure will return the new
      identity, but a call outside the procedure will return the last identity
      value that was generated before a call was made to the procedure.</p>
<p>The last inserted IDENTITY value can also be retrieved via JDBC,
      by specifying the Statement or PreparedStatement object to return the
      generated value.</p>
<p>The next IDENTITY value to be used can be changed with the
      following statement. Note that this statement is not used in normal
      operation and is only for special purposes, for example resetting the
      identity generator: </p>
<pre class="programlisting"> ALTER TABLE ALTER COLUMN &lt;column name&gt; RESTART WITH &lt;new value&gt;;</pre>
<p>For
      backward compatibility, support has been retained for <code class="literal">CREATE
      TABLE &lt;tablename&gt;(&lt;colname&gt; IDENTITY, ...)</code> as a
      shortcut which defines the column both as an IDENTITY column and a
      PRIMARY KEY column. Also, for backward compatibility, it is possible to
      use NULL as the value of an IDENTITY column in an INSERT statement and
      the value will be generated automatically. You should avoid these
      compatibility features as they may be removed from future versions of
      HyperSQL.</p>
<p>In the following example, the identity value for the first INSERT
      statement is generated automatically using the DEFAULT keyword. The
      second INSERT statement uses a call to the IDENTITY() function to
      populate a row in the child table with the generated identity
      value.</p>
<div class="informalexample">
<pre class="programlisting"> CREATE TABLE star (id INTEGER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY, 
   firstname VARCHAR(20),
   lastname VARCHAR(20))
 CREATE TABLE movies (starid INTEGER, movieid INTEGER PRIMARY KEY, title VARCHAR(40)) 
 INSERT INTO star (id, firstname, lastname) VALUES (DEFAULT, 'Felix', 'the Cat')
 INSERT INTO movies (starid, movieid, title) VALUES (IDENTITY(), 10, 'Felix in Hollywood')
</pre>
</div>
<p>HyperSQL 2.1 also supports IDENTITY columns that use an external,
      named SEQUENCE object. This feature is not part of the SQL Standard. The
      example below uses this type of IDENTITY. Note the use of CURRENT VALUE
      FOR seq here is multi-session safe. The returned value is the last value
      used by this session when the row was inserted into the star table. This
      value is available until the transaction is committed. After commit,
      NULL is returned by the CURRENT VALUE FOR expression until the SEQUENCE
      is used again.</p>
<div class="informalexample">
<pre class="programlisting"> CREATE SEQUENCE seq
 CREATE TABLE star (id INTEGER GENERATED BY DEFAULT AS SEQUENCE seq PRIMARY KEY, 
   firstname VARCHAR(20),
   lastname VARCHAR(20))
 CREATE TABLE movies (starid INTEGER, movieid INTEGER PRIMARY KEY, title VARCHAR(40)) 
 INSERT INTO star (id, firstname, lastname) VALUES (DEFAULT, 'Felix', 'the Cat')
 INSERT INTO movies (starid, movieid, title) VALUES (CURRENT VALUE FOR seq, 10, 'Felix in Hollywood')
</pre>
</div>
</div>
<div class="section" title="Tables">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dbc_tables"></a>Tables</h3>
</div>
</div>
</div>
<p>In the SQL environment, tables are the most essential components,
      as they hold all persistent data.</p>
<p>If TABLE is considered as metadata (i.e. without its actual data)
      it is called a <span class="emphasis"><em>relation</em></span> in relational theory. It
      has one or more columns, with each column having a distinct name and a
      data type. A table usually has one or more constraints which limit the
      values that can potentially be stored in the TABLE. These constraints
      are discussed in the next section.</p>
<p>A single column of the table can be defined as IDENTITY. The
      values stored in this column are auto-generated and are based on an
      (unnamed) identity sequence, or optionally, a named SEQUENCE
      object.</p>
</div>
<div class="section" title="Views">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dbc_views"></a>Views</h3>
</div>
</div>
</div>
<p>A VIEW is similar to a TABLE but it does not permanently contain
      rows of data. A view is defined as a QUERY EXPRESSION, which is often a
      SELECT statement that references views and tables, but it can also
      consist of a TABLE CONSTRUCTOR that does not reference any tables or
      views.</p>
<p>A view has many uses:</p>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>Hide the structure and column names of tables. The view can
          represent one or more tables or views as a separate table. This can
          include aggregate data, such as sums and averages, from other
          tables.</p>
</li>
<li class="listitem">
<p>Allow access to specific rows in a table. For example, allow
          access to records that were added since a given date, while hiding
          older records.</p>
</li>
<li class="listitem">
<p>Allow access to specific columns. For example allow access to
          columns that contain non-confidential information. Note that this
          can also be achieved with the GRANT SELECT statement, using
          column-level privileges</p>
</li>
</ul>
</div>
<p>A VIEW that returns the columns of a single ordinary TABLE is
      <em class="glossterm">updatable</em> if the query expression of the view is
      an updatable query expression as discussed in the <a class="link" href="#dataaccess-chapt" title="Chapter&nbsp;7.&nbsp;Data Access and Change">Data Access and Change</a>
      chapter. Some <em class="glossterm">updatable</em> views are
      <em class="glossterm">insertable-into</em> because the query expression is
      insertable-into. In these views, each column of the query expressions
      must be a column of the underlying table and those columns of the
      underlying table that are not in the view must have a default clause, or
      be an IDENTITY or GENERATED column. When rows of an updatable view are
      updated, or new rows are inserted, or rows are deleted, these changes
      are reflected in the base table. A VIEW definition may specify that the
      inserted or updated rows conform to the search condition of the view.
      This is done with the CHECK OPTION clause.</p>
<p>A view that is not updatable according to the above paragraph can
      be made updatable or insertable-into by adding INSTEAD OF triggers to
      the view. These triggers contain statements to use the submitted data to
      modify the contents of the underlying tables of the view separately. For
      example, a view that represents a SELECT statements that joins two
      tables can have an INSTEAD OF DELETE trigger with two DELETE statements,
      one for each table. Views that have an INSTEAD OF trigger are called
      TRIGGER INSERTABLE, TRIGGER UPDATABLE, etc. according to the triggers
      that have been defined.</p>
<p>Views share a name-space with tables.</p>
</div>
<div class="section" title="Constraints">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dbc_constraints"></a>Constraints</h3>
</div>
</div>
</div>
<p>A CONSTRAINT is a child schema object and can belong to a DOMAIN
      or a TABLE. CONSTRAINT objects can be defined without specifying a name.
      In this case the system generates a name for the new object beginning
      with "SYS_".</p>
<p>In a DOMAIN, CHECK constraints can be defined that limits the
      value represented by the DOMAIN. These constraints work exactly like a
      CHECK constraint on a single column of a table as described
      below.</p>
<p>In a TABLE, a constraint takes three basic forms.</p>
<p>
<span class="bold"><strong>CHECK</strong></span>
</p>
<p>A CHECK constraint consists of a <code class="literal">&lt;search
      condition&gt;</code> that must not be false (can be unknown) for each
      row of the table. The <code class="literal">&lt;search condition&gt;</code> can
      reference all the columns of the current row, and if it contains a
      <code class="literal">&lt;subquery&gt;</code>, other tables and views in the
      database (excluding its own table).</p>
<p>
<span class="bold"><strong>NOT NULL</strong></span>
</p>
<p>A simple form of check constraint is the NOT NULL constraint,
      which applies to a single column.</p>
<p>
<span class="bold"><strong>UNIQUE</strong></span>
</p>
<p>A UNIQUE constraint is based on an equality comparison of values
      of specific columns (taken together) of one row with the same values
      from each of the other rows. The result of the comparison must never be
      true (can be false or unknown). If a row of the table has NULL in any of
      the columns of the constraint, it conforms to the constraint. A unique
      constraint on multiple columns (c1, c2, c3, ..) means that in no two
      rows, the sets of values for the columns can be equal unless at lease
      one of them is NULL. Each single column taken by itself can have repeat
      values in different rows. The following example satisfies a UNIQUE
      constraint on the two columns</p>
<div class="example">
<a name="N10DE7"></a>
<p class="title">
<b>Example&nbsp;4.4.&nbsp;Column values which satisfy a 2-column UNIQUE
        constraint</b>
</p>
<div class="example-contents">
<table summary="Simple list" border="0" class="simplelist">
<tr>
<td>1,</td><td>2</td>
</tr>
<tr>
<td>2,</td><td>1</td>
</tr>
<tr>
<td>2,</td><td>2</td>
</tr>
<tr>
<td>NULL,</td><td>1</td>
</tr>
<tr>
<td>NULL,</td><td>1</td>
</tr>
<tr>
<td>1,</td><td>NULL</td>
</tr>
<tr>
<td>NULL,</td><td>NULL</td>
</tr>
<tr>
<td>NULL,</td><td>NULL</td>
</tr>
</table>
</div>
</div>
<br class="example-break">
<p>If the SET DATABASE SQL UNIQUE NULLS FALSE has been set, then if
      not all the values set of columns are null, the not null values are
      compared and it is disallowed to insert identical rows that contain at
      least one not-null value.</p>
<p>
<span class="bold"><strong>PRIMARY KEY</strong></span>
</p>
<p>A PRIMARY KEY constraint is equivalent to a UNIQUE constraint on
      one or more NOT NULL columns. Only one PRIMARY KEY can be defined in
      each table.</p>
<p>
<span class="bold"><strong>FOREIGN KEY</strong></span>
</p>
<p>A FOREIGN key constraint is based on an equality comparison
      between values of specific columns (taken together) of each row with the
      values of the columns of a UNIQUE constraint on another table or the
      same table. The result of the comparison must never be false (can be
      unknown). A special form of FOREIGN KEY constraint, based on its CHECK
      clause, allows the result to be unknown only if the values for all
      columns are NULL. A FOREIGN key can be declared only if a UNIQUE
      constraint exists on the referenced columns.</p>
<p>Constraints share a name space with assertions.</p>
</div>
<div class="section" title="Assertions">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dbc_assertions"></a>Assertions</h3>
</div>
</div>
</div>
<p>An ASSERTION is a top-level schema objects. It consists of a
      <code class="literal">&lt;search condition&gt;</code> that must not be false (can
      be unknown). HyperSQL does not yet support assertions.</p>
<p>Assertions share a name-space with constraints</p>
</div>
<div class="section" title="Triggers">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dbc_triggers"></a>Triggers</h3>
</div>
</div>
</div>
<p>A TRIGGER is a child schema object that always belongs to a TABLE
      or a VIEW.</p>
<p>Each time a DELETE, UPDATE or INSERT is performed on the table or
      view, additional actions are taken by the triggers that have been
      declared on the table or view.</p>
<p>Triggers are discussed in detail in <a class="link" href="#triggers-chapt" title="Chapter&nbsp;9.&nbsp;Triggers">Triggers</a> chapter.</p>
</div>
<div class="section" title="Routines">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dbc_routines"></a>Routines</h3>
</div>
</div>
</div>
<p>Routines are user-defined functions or procedures. The names and
      usage of functions and procedures are different. FUNCTION is a routine
      that can be referenced in many types of statements. PROCEDURE is a
      routine that can be referenced only in a CALL statement.</p>
<p>There is a separate name-space for routines.</p>
<p>Because of the possibility of overloading, each routine can have
      more than one name. The name of the routine is the same for all
      overloaded variants, but each variant has a <em class="glossterm">specific
      name</em>, different from all other routine names and specific
      names in the schema. The <em class="glossterm">specific name</em> can be
      specified in the routine definition statement. Otherwise it is assigned
      by the engine. The specific name is used only for schema manipulation
      statements, which need to reference a specific variant of the routine.
      For example, if a routine has two signatures, each signature has its own
      <em class="glossterm">specific name</em>. This allows the user to drop one
      of the signatures while keeping the other.</p>
<p>Routines are discussed in detail in chapter <a class="link" href="#sqlroutines-chapt" title="Chapter&nbsp;8.&nbsp;SQL-Invoked Routines">SQL-Invoked Routines</a> .</p>
</div>
<div class="section" title="Indexes">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dbc_indexes"></a>Indexes</h3>
</div>
</div>
</div>
<p>Indexes are an implementation-defined extension to the SQL
      Standard. HyperSQL has a dedicated name-space for indexes in each
      schema.</p>
</div>
</div>
<div class="section" title="Statements for Schema Definition and Manipulation">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="dbc_schema_def_statements"></a>Statements for Schema Definition and Manipulation</h2>
</div>
</div>
</div>
<p>Schemas and schema objects can be created, modified and dropped. The
    SQL Standard defines a range of statements for this purpose. HyperSQL
    supports many additional statements, especially for changing the
    properties of existing schema objects.</p>
<div class="section" title="Common Elements and Statements">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dbc_common_elements"></a>Common Elements and Statements</h3>
</div>
</div>
</div>
<p>These elements and statements are used for different types of
      object. They are described here, before the statements that can use
      them.</p>
<a name="N10E63" class="indexterm"></a>
<p>
<span class="bold"><strong>identifier</strong></span>
</p>
<p>
<span class="emphasis"><em>definition of identifier</em></span>
</p>
<p>
<code class="literal">&lt;identifier&gt; ::= &lt;regular identifier&gt; |
      &lt;delimited identifier&gt; | &lt;SQL language identifier&gt;
      </code>
</p>
<p>
<code class="literal">&lt;delimited identifier&gt; ::= &lt;double quote&gt;
      &lt;character sequence&gt; &lt;double quote&gt;</code>
</p>
<p>
<code class="literal">&lt;regular identifier&gt; ::= &lt;special character
      sequence&gt;</code>
</p>
<p>
<code class="literal">&lt;SQL language identifier&gt; ::= &lt;special
      character sequence&gt;</code>
</p>
<p>A <code class="literal">&lt;delimited identifier&gt;</code> is a sequence of
      characters enclosed with double-quote symbols. All characters are
      allowed in the character sequence.</p>
<p>A <code class="literal">&lt;regular identifier&gt;</code> is a special
      sequence of characters. It consists of letters, digits and the
      underscore characters. It must begin with a letter. All the letters are
      translated to their upper-case version.</p>
<p>The database setting, <code class="literal">SET DATABASE SQL REGULAR NAMES
      FALSE</code> can be used to relax the rules for regular identifier.
      With this setting, an underscore character can appear at the start of
      the regular identifier, and the dollar sign character can be used in the
      identifier.</p>
<p>A <code class="literal">&lt;SQL language identifier&gt;</code> is similar to
      <code class="literal">&lt;regular identifier&gt;</code> but the letters can range
      only from A-Z in the ASCII character set. This type of identifier is
      used for names of CHARACTER SET objects.</p>
<p>If the character sequence of a delimited identifier is the same as
      an undelimited identifier, it represents the same identifier. For
      example "JOHN" is the same identifier as JOHN. In a <code class="literal">&lt;regular
      identifier&gt;</code> the case-normal form is considered for
      comparison. This form consists of the upper-case equivalent of all the
      letters. When a database object is created with one of the CREATE
      statements or renamed with the ALTER statement, if the name is enclosed
      in double quotes, the exact name is used as the case-normal form. But if
      it is not enclosed in double quotes, the name is converted to uppercase
      and this uppercase version is stored in the database as the case-normal
      form.</p>
<p>The character sequence length of all identifiers must be between 1
      and 128 characters.</p>
<p>A reserved word is one that is used by the SQL Standard for
      special purposes. It is similar to a <code class="literal">&lt;regular
      identifier&gt;</code> but it cannot be used as an identifier for user
      objects. If a reserved word is enclosed in double quote characters, it
      becomes a quoted identifier and can be used for database objects.</p>
<p>Case sensitivity rules for identifiers can be described simply as
      follows:</p>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>all parts of SQL statements are converted to upper case before
          processing, <span class="emphasis"><em>except identifiers in double quotes and
          strings in single quotes</em></span>
</p>
</li>
<li class="listitem">
<p>identifiers, both unquoted and double quoted, are then treated
          as case-sensitive</p>
</li>
<li class="listitem">
<p>most database engines follow the same rule, except, in some
          respects, MySQL and MS SQLServer.</p>
</li>
</ul>
</div>
<a name="N10EAC" class="indexterm"></a>
<p>
<span class="bold"><strong>CASCADE or RESTRICT</strong></span>
</p>
<p>
<span class="emphasis"><em>drop behavior</em></span>
</p>
<p>
<code class="literal">&lt;drop behavior&gt; ::= CASCADE |
      RESTRICT</code>
</p>
<p>The <code class="literal">&lt;drop behavior&gt;</code> is a required element
      of statements that drop a SCHEMA or a schema object. If
      <code class="literal">&lt;drop behavior&gt;</code> is not specified then
      <code class="literal">RESTRICT</code> is implicit. It determines the effect of the
      statement if there are other objects in the catalog that reference the
      SCHEMA or the schema object. If RESTRICT is specified, the statement
      fails if there are referencing objects. If CASCADE is specified, all the
      referencing objects are modified or dropped with cascading effect.
      Whether a referencing object is modified or dropped, depends on the kind
      of schema object that is dropped.</p>
<a name="N10EC6" class="indexterm"></a>
<p>
<span class="bold"><strong>IF EXISTS</strong></span>
</p>
<p>
<span class="emphasis"><em>drop condition (HyperSQL)</em></span>
</p>
<p>
<code class="literal">&lt;if exists clause&gt; ::= IF
      EXISTS</code>
</p>
<p>This clause is not part of the SQL standard and is a HyperSQL
      extension to some commands that drop objects (schemas, tables, views,
      sequences and indexes). If it is specified, then the statement does not
      return an error if the drop statement is issued on a non-existent
      object.</p>
<a name="N10ED7" class="indexterm"></a>
<p>
<span class="bold"><strong>SPECIFIC</strong></span>
</p>
<p>
<span class="emphasis"><em>specific routine designator</em></span>
</p>
<p>
<code class="literal">&lt;specific routine designator&gt; ::= SPECIFIC
      &lt;routine type&gt; &lt;specific name&gt; </code>
</p>
<p>
<code class="literal">&lt;routine type&gt; ::= ROUTINE | FUNCTION |
      PROCEDURE</code>
</p>
<p>This clause is used in statements that need to specify one of the
      multiple versions of an overloaded routine. The <code class="literal">&lt;specific
      name&gt;</code> is the one specified in the <code class="literal">&lt;routine
      definition&gt;</code> statement.</p>
</div>
<div class="section" title="Renaming Objects">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dbc_renaming"></a>Renaming Objects</h3>
</div>
</div>
</div>
<a name="N10EF5" class="indexterm"></a>
<p>
<span class="bold"><strong>RENAME</strong></span>
</p>
<p>
<span class="emphasis"><em>rename statement (HyperSQL)</em></span>
</p>
<p>
<code class="literal">&lt;rename statement&gt; ::= ALTER &lt;object type&gt;
      &lt;name&gt; RENAME TO &lt;new name&gt;</code>
</p>
<p>
<code class="literal">&lt;object type&gt; ::= CATALOG | SCHEMA | DOMAIN |
      TYPE | TABLE | CONSTRAINT | INDEX | ROUTINE | SPECIFIC
      ROUTINE</code>
</p>
<p>
<code class="literal">&lt;column rename statement&gt; ::= ALTER TABLE
      &lt;table name&gt; ALTER COLUMN &lt;name&gt; RENAME TO &lt;new
      name&gt;</code>
</p>
<p>This statement is used to rename an existing object. It is not
      part of the SQL Standard. The specified <code class="literal">&lt;name&gt;</code>
      is the existing name, which can be qualified with a schema name, while
      the <code class="literal">&lt;new name&gt;</code> is the new name for the
      object.</p>
</div>
<div class="section" title="Commenting Objects">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dbc_commenting"></a>Commenting Objects</h3>
</div>
</div>
</div>
<a name="N10F16" class="indexterm"></a>
<p>
<span class="bold"><strong>COMMENT</strong></span>
</p>
<p>
<span class="emphasis"><em>comment statement (HyperSQL)</em></span>
</p>
<p>
<code class="literal">&lt;comment statement&gt; ::= COMMENT ON { TABLE |
      COLUMN | ROUTINE } &lt;name&gt; IS &lt;character string
      literal&gt;</code>
</p>
<p>Adds a comment to the object metadata, which can later be read
      from an INFORMATION_SCHEMA view. This command is not part of the SQL
      Standard. The strange syntax is due to compatibility with other database
      engines that support the statement.<code class="literal"> The &lt;name&gt;</code>
      is the name of a table, view, column or routine. The name of the column
      consists of dot-separated<code class="literal"> &lt;table name&gt; . &lt;column
      name&gt;</code>. The name of the table, view or routine can be a
      simple name. All names can be qualified with a schema name. If there is
      already a comment on the object, the new comment will replace it.</p>
<p>The comments appear in the results returned by JDBC
      DatabaseMetaData methods, getTables() and getColumns(). The
      INFORMATION_SCHEMA.SYSTEM_COMMENTS view contains the comments. You can
      query this view using the schema, table, and column names to retrieve
      the comments.</p>
</div>
<div class="section" title="Schema Creation">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dbc_schema_creation"></a>Schema Creation</h3>
</div>
</div>
</div>
<a name="N10F33" class="indexterm"></a>
<p>
<span class="bold"><strong>CREATE SCHEMA</strong></span>
</p>
<p>
<span class="emphasis"><em>schema definition</em></span>
</p>
<p>The CREATE_SCHEMA or DBA role is required in order to create a
      schema. A schema can be created with or without schema objects. Schema
      objects can always be added after creating the schema, or existing ones
      can be dropped. Within the <code class="literal">&lt;schema definition&gt;</code>
      statement, all schema object creation takes place inside the newly
      created schema. Therefore, if a schema name is specified for the schema
      objects, the name must match that of the new schema. In addition to
      statements for creating schema objects, the statement can include
      instances of <code class="literal">&lt;grant statement&gt;</code> and
      <code class="literal">&lt;role definition&gt;</code>. This is a curious aspect of
      the SQL standard, as these elements do not really belong to schema
      creation.</p>
<p>
<code class="literal">&lt;schema definition&gt; ::= CREATE SCHEMA &lt;schema
      name clause&gt; [ &lt;schema character set specification&gt; ] [
      &lt;schema element&gt;... ]</code>
</p>
<p>
<code class="literal">&lt;schema name clause&gt; ::= &lt;schema name&gt; |
      AUTHORIZATION &lt;authorization identifier&gt; | &lt;schema name&gt;
      AUTHORIZATION &lt;authorization identifier&gt;</code>
</p>
<p>If the name of the schema is specified simply as
      <code class="literal">&lt;schema name&gt;</code>, then the AUTHORIZATION is the
      current user. Otherwise, the specified <code class="literal">&lt;authorization
      identifier&gt;</code> is used as the AUTHORIZATION for the schema. If
      <code class="literal">&lt;schema name&gt;</code> is omitted, then the name of the
      schema is the same as the specified <code class="literal">&lt;authorization
      identifier&gt;</code>.</p>
<p>
<code class="literal">&lt;schema element&gt; ::= &lt;table definition&gt; |
      &lt;view definition&gt; | &lt;domain definition&gt; | &lt;character set
      definition&gt; | &lt;collation definition&gt; | &lt;transliteration
      definition&gt; | &lt;assertion definition&gt; | &lt;trigger
      definition&gt; | &lt;user-defined type definition&gt; | &lt;user-defined
      cast definition&gt; | &lt;user-defined ordering definition&gt; |
      &lt;transform definition&gt; | &lt;schema routine&gt; | &lt;sequence
      generator definition&gt; | &lt;grant statement&gt; | &lt;role
      definition&gt;</code>
</p>
<p>An example of the command is given below. Note that a single
      semicolon appears at the end. There should be no semicolon between the
      statements:</p>
<pre class="programlisting"> CREATE SCHEMA ACCOUNTS AUTHORIZATION DBA
   CREATE TABLE AB(A INTEGER, ...)
   CREATE TABLE CD(C CHAR(10), ...)
   CREATE VIEW VI AS SELECT ...
   GRANT SELECT ON AB TO PUBLIC
   GRANT SELECT ON CD TO JOE;
</pre>
<p>It is not really necessary to create a schema and all its objects
      as one command. The schema can be created first, and its objects can be
      created one by one.</p>
<a name="N10F67" class="indexterm"></a>
<p>
<span class="bold"><strong>DROP SCHEMA</strong></span>
</p>
<p>
<span class="emphasis"><em>drop schema statement</em></span>
</p>
<p>
<code class="literal">&lt;drop schema statement&gt; ::= DROP SCHEMA [ IF
      EXISTS ] &lt;schema name&gt; [ IF EXISTS ] &lt;drop behavior&gt;
      </code>
</p>
<p>This command destroys an existing schema. If <code class="literal">&lt;drop
      behavior&gt;</code> is <code class="literal">RESTRICT</code>, the schema must
      be empty, otherwise an error is raised. If <code class="literal">CASCADE</code> is
      specified, then all the objects contained in the schema are destroyed
      with a CASCADE option.</p>
</div>
<div class="section" title="Table Creation">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dbc_table_creation"></a>Table Creation</h3>
</div>
</div>
</div>
<a name="N10F85" class="indexterm"></a>
<p>
<span class="bold"><strong>CREATE TABLE</strong></span>
</p>
<p>
<span class="emphasis"><em>table definition</em></span>
</p>
<p>
<code class="literal">&lt;table definition&gt; ::= CREATE [ { &lt;table
      scope&gt; | &lt;table type&gt; } ] TABLE &lt;table name&gt; &lt;table
      contents source&gt; [ ON COMMIT { PRESERVE | DELETE } ROWS
      ]</code>
</p>
<p>
<code class="literal">&lt;table scope&gt; ::= { GLOBAL | LOCAL }
      TEMPORARY</code>
</p>
<p>
<code class="literal">&lt;table type&gt; :: = MEMORY |
      CACHED</code>
</p>
<p>
<code class="literal">&lt;table contents source&gt; ::= &lt;table element
      list&gt; | &lt;as subquery clause&gt;</code>
</p>
<p>
<code class="literal">&lt;table element list&gt; ::= &lt;left paren&gt;
      &lt;table element&gt; [ { &lt;comma&gt; &lt;table element&gt; }... ]
      &lt;right paren&gt;</code>
</p>
<p>
<code class="literal">&lt;table element&gt; ::= &lt;column definition&gt; |
      &lt;table constraint definition&gt; | &lt;like
      clause&gt;</code>
</p>
<p>
<span class="emphasis"><em>like clause</em></span>
</p>
<p>A <code class="literal">&lt;like clause&gt;</code> copies all column
      definitions from another table into the newly created table. Its three
      options indicate if the <code class="literal">&lt;default clause&gt;</code>,
      <code class="literal">&lt;identity column specification&gt;</code> and
      <code class="literal">&lt;generation clause&gt;</code> associated with the column
      definitions are copied or not. If an option is not specified, it
      defaults to <code class="literal">EXCLUDING</code>. The <code class="literal">&lt;generation
      clause&gt;</code> refers to columns that are generated by an
      expression but not to identity columns. All NOT NULL constraints are
      copied with the original columns, other constraints are not. The
      <code class="literal">&lt;like clause&gt;</code> can be used multiple times,
      allowing the new table to have copies of the column definitions of one
      or more other tables.</p>
<div class="informalexample">
<pre class="programlisting"> CREATE TABLE t (id INTEGER PRIMARY KEY, LIKE atable INCLUDING DEFAULTS EXCLUDING IDENTITY)
</pre>
</div>
<p>
<code class="literal">&lt;like clause&gt; ::= LIKE &lt;table name&gt; [
      &lt;like options&gt; ]</code>
</p>
<p>
<code class="literal">&lt;like options&gt; ::= &lt;like
      option&gt;...</code>
</p>
<p>
<code class="literal">&lt;like option&gt; ::= &lt;identity option&gt; |
      &lt;column default option&gt; | &lt;generation
      option&gt;</code>
</p>
<p>
<code class="literal">&lt;identity option&gt; ::= INCLUDING IDENTITY |
      EXCLUDING IDENTITY</code>
</p>
<p>
<code class="literal">&lt;column default option&gt; ::= INCLUDING DEFAULTS |
      EXCLUDING DEFAULTS</code>
</p>
<p>
<code class="literal">&lt;generation option&gt; ::= INCLUDING GENERATED |
      EXCLUDING GENERATED</code>
</p>
<p>
<span class="emphasis"><em>as subquery clause</em></span>
</p>
<p>
<code class="literal">&lt;as subquery clause&gt; ::= [ &lt;left paren&gt;
      &lt;column name list&gt; &lt;right paren&gt; ] AS &lt;table subquery&gt;
      { WITH NO DATA | WITH DATA }</code>
</p>
<p>An <code class="literal">&lt;as subquery clause&gt;</code> used in table
      definition creates a table based on a <code class="literal">&lt;table
      subquery&gt;</code>. This kind of table definition is similar to a
      view definition. If <code class="literal">WITH DATA</code> is specified, then the
      new table will contain the rows of data returned by the
      <code class="literal">&lt;table subquery&gt;</code>.</p>
<div class="informalexample">
<pre class="programlisting"> CREATE TABLE t (a, b, c) AS (SELECT * FROM atable) WITH DATA
</pre>
</div>
<a name="N10FE9" class="indexterm"></a>
<p>
<span class="emphasis"><em>column definition</em></span>
</p>
<p>A column definition consists of a <code class="literal">&lt;column
      name&gt;</code> and in most cases a <code class="literal">&lt;data
      type&gt;</code> or <code class="literal">&lt;domain name&gt;</code> as minimum.
      The other elements of <code class="literal">&lt;column definition&gt;</code> are
      optional. Each <code class="literal">&lt;column name&gt;</code> in a table is
      unique.</p>
<p>
<code class="literal">&lt;column definition&gt; ::= &lt;column name&gt; [
      &lt;data type or domain name&gt; ] [ &lt;default clause&gt; |
      &lt;identity column specification&gt; | &lt;identity column sequence
      specification&gt; | &lt;generation clause&gt; ] [ &lt;column constraint
      definition&gt;... ] [ &lt;collate clause&gt; ]</code>
</p>
<p>
<code class="literal">&lt;data type or domain name&gt; ::= &lt;data type&gt;
      | &lt;domain name&gt;</code>
</p>
<p>
<code class="literal">&lt;column constraint definition&gt; ::= [
      &lt;constraint name definition&gt; ] &lt;column constraint&gt; [
      &lt;constraint characteristics&gt; ]</code>
</p>
<p>
<code class="literal">&lt;column constraint&gt; ::= NOT NULL | &lt;unique
      specification&gt; | &lt;references specification&gt; | &lt;check
      constraint definition&gt;</code>
</p>
<p>A <code class="literal">&lt;column constraint definition&gt;</code> is a
      shortcut for a <code class="literal">&lt;table constraint definition&gt;</code>. A
      constraint that is defined in this way is automatically turned into a
      table constraint. A name is automatically generated for the constraint
      and assigned to it.</p>
<p>If a <code class="literal">&lt;collate clause&gt;</code> is specified,
      then a UNIQUE or PRIMARY KEY constraint or an INDEX on the column will
      use the specified collation. Otherwise the default collation for the
      database is used.</p>
<a name="N1101B" class="indexterm"></a>
<p>
<span class="emphasis"><em>generated columns</em></span>
</p>
<p>The value of a column can be autogenerated in two ways.</p>
<p>One way is specific to columns of integral types (INTEGER, BIGINT,
      etc.) and associates a sequence generator with the column. When a new
      row is inserted into the table, the value of the column is generated as
      the next available value in the sequence.</p>
<p>The SQL Standard supports the use of unnamed sequences with the
      IDENTITY keyword. In addition, HyperSQL supports the use of a named
      SEQUENCE object, which must be in the same schema as the table.</p>
<p>
<code class="literal">&lt;identity column specification&gt; ::= GENERATED {
      ALWAYS | BY DEFAULT } AS IDENTITY [ &lt;left paren&gt; &lt;common
      sequence generator options&gt; &lt;right paren&gt; ]</code>
</p>
<p>
<code class="literal">&lt;identity column sequence specification ::=
      GENERATED BY DEFAULT AS SEQUENCE &lt;sequence name&gt;
      </code>
</p>
<p>The <code class="literal">&lt;identity column specification&gt;</code> or
      <code class="literal">&lt;identity column sequence specification&gt;</code> can be
      specified for only a single column of the table.</p>
<p>The <code class="literal">&lt;identity column specification&gt;</code> is
      used for columns which represent values based on an unnamed sequence
      generator. It is possible to insert a row into the table without
      specifying a value for the column. The value is then generated by the
      sequence generators according to its rules. An identity column may or
      may not be the primary key. Example below:</p>
<div class="informalexample">
<pre class="programlisting"> CREATE TABLE t (id INTEGER GENERATED ALWAYS AS IDENTITY(START WITH 100), name VARCHAR(20) PRIMARY KEY)
</pre>
</div>
<p>The <code class="literal">&lt;identity column sequence
      specification&gt;</code> is used when the column values are based on
      a named SEQUENCE object (which must already exist). Example
      below:</p>
<div class="informalexample">
<pre class="programlisting"> CREATE TABLE t (id INTEGER GENERATED BY DEFAULT AS SEQUENCE s, name VARCHAR(20) PRIMARY KEY)
</pre>
</div>
<p>Inserting rows is done in the same way for a named or unnamed
      sequence generator. In both cases, if no value is specified to be
      inserted, or the DEFAULT keyword is used for the column, the value is
      generated by the sequence generator. If a value is specified, this value
      is used if the column definition has the BY DEFAULT specification. If
      the column definition has the ALWAYS specification, a value can be
      specified but the OVERRIDING SYSTEM VALUES must be specified in the
      INSERT statement.</p>
<p>The other way in which the column value is autogenerated is by
      using the values of other columns in the same row. This method is often
      used to create an index on a value that is derived from other column
      values.</p>
<p>
<code class="literal">&lt;generation clause&gt; ::= GENERATED ALWAYS AS
      &lt;generation expression&gt;</code>
</p>
<p>
<code class="literal">&lt;generation expression&gt; ::= &lt;left paren&gt;
      &lt;value expression&gt; &lt;right paren&gt;</code>
</p>
<p>The <code class="literal">&lt;generation clause&gt;</code> is used for
      special columns which represent values based on the values held in other
      columns in the same row. The <code class="literal">&lt;value expression&gt;</code>
      must reference only other, non-generated, columns of the table in the
      same row. Any function used in the expression must be deterministic and
      must not access SQL-data. No <code class="literal">&lt;query expression&gt;</code>
      is allowed. When <code class="literal">&lt;generation clause&gt;</code> is used,
      <code class="literal">&lt;data type&gt;</code> must be specified.</p>
<p>A generated column can be part of a foreign key or unique
      constraints or a column of an index. This capability is the main reason
      for using generated columns. A generated column may contain a formula
      that computes a value based on the values of other columns. Fast
      searches of the computed value can be performed when an index is
      declared on the generated column. Or the computed values can be declared
      to be unique, using a UNIQUE constraint on the table. The computed
      column cannot be overridden by user supplied values. When a row is
      updated and the column values change, the generated columns are computed
      with the new values.</p>
<p>When a row is inserted into a table, or an existing row is
      updated, no value except DEFAULT can be specified for a generated
      column. In the example below, data is inserted into the non-generated
      columns and the generated column will contain 'Felix the Cat' or 'Pink
      Panther'.</p>
<div class="informalexample">
<pre class="programlisting"> CREATE TABLE t (id INTEGER PRIMARY KEY, 
   firstname VARCHAR(20),
   lastname VARCHAR(20), 
   fullname VARCHAR(40) GENERATED ALWAYS AS (firstname || ' ' || lastname)) 
 INSERT INTO t (id, firstname, lastname) VALUES (1, 'Felix', 'the Cat')
 INSERT INTO t (id, firstname, lastname, fullname) VALUES (2, 'Pink', 'Panther', DEFAULT)
</pre>
</div>
<a name="N11069" class="indexterm"></a>
<p>
<span class="bold"><strong>DEFAULT</strong></span>
</p>
<p>
<span class="emphasis"><em>default clause</em></span>
</p>
<p>A default clause can be used if GENERATED is not specified. If a
      column has a <code class="literal">&lt;default clause&gt;</code> then it is
      possible to insert a row into the table without specifying a value for
      the column.</p>
<p>
<code class="literal">&lt;default clause&gt; ::= DEFAULT &lt;default
      option&gt;</code>
</p>
<p>
<code class="literal">&lt;default option&gt; ::= &lt;literal&gt; |
      &lt;datetime value function&gt; | USER | CURRENT_USER | CURRENT_ROLE |
      SESSION_USER | SYSTEM_USER | CURRENT_CATALOG | CURRENT_SCHEMA |
      CURRENT_PATH | NULL</code>
</p>
<p>The type of the <code class="literal">&lt;default option&gt;</code> must
      match the type of the column.</p>
<p>In PGS (PostgreSQL) compatibility mode, a NEXTVAL function can be
      used. Also, in MSS compatibility mode, the default value can be enclosed
      in parentheses.</p>
<a name="N11087" class="indexterm"></a>
<p>
<span class="bold"><strong>CONSTRAINT</strong></span>
</p>
<p>
<span class="emphasis"><em>constraint name and
      characteristics</em></span>
</p>
<p>
<code class="literal">&lt;constraint name definition&gt; ::= CONSTRAINT
      &lt;constraint name&gt;</code>
</p>
<p>
<code class="literal">&lt;constraint characteristics&gt; ::= &lt;constraint
      check time&gt; [ [ NOT ] DEFERRABLE [ &lt;constraint check time&gt; ]
      ]</code>
</p>
<p>
<code class="literal">&lt;constraint check time&gt; ::= INITIALLY DEFERRED |
      INITIALLY IMMEDIATE</code>
</p>
<p>Specify the name of a constraint and its characteristics. By
      default the constraint is <code class="literal">NOT DEFERRABLE</code> and
      <code class="literal">INITIALLY IMMEDIATE</code>. This means the constraint is
      enforced as soon as a data change statement is executed. If
      <code class="literal">INITIALLY DEFERRED</code> is specified, then the constraint
      is enforced when the session commits. The characteristics must be
      compatible. The constraint check time can be changed temporarily for an
      SQL session. HyperSQL does not support deferring constraint enforcement.
      This feature of the SQL Standard has been criticised because it allows a
      session to read uncommitted data that violates database integrity
      constraints but has not yet been checked.</p>
<a name="N110A7" class="indexterm"></a>
<p>
<span class="bold"><strong>CONSTRAINT</strong></span>
</p>
<p>
<span class="emphasis"><em>table constraint definition</em></span>
</p>
<p>
<code class="literal">&lt;table constraint definition&gt; ::= [
      &lt;constraint name definition&gt; ] &lt;table constraint&gt; [
      &lt;constraint characteristics&gt; ]</code>
</p>
<p>
<code class="literal">&lt;table constraint&gt; ::= &lt;unique constraint
      definition&gt; | &lt;referential constraint definition&gt; | &lt;check
      constraint definition&gt;</code>
</p>
<p>Three kinds of constraint can be defined on a table: UNIQUE
      (including PRIMARY KEY), FOREIGN KEY and CHECK. Each kind has its own
      rules to limit the values that can be specified for different columns in
      each row of the table.</p>
<a name="N110BB" class="indexterm"></a><a name="N110C0" class="indexterm"></a>
<p>
<span class="bold"><strong>UNIQUE</strong></span>
</p>
<p>
<span class="emphasis"><em>unique constraint definition</em></span>
</p>
<p>
<code class="literal">&lt;unique constraint definition&gt; ::= &lt;unique
      specification&gt; &lt;left paren&gt; &lt;unique column list&gt;
      &lt;right paren&gt; | UNIQUE ( VALUE )</code>
</p>
<p>
<code class="literal">&lt;unique specification&gt; ::= UNIQUE | PRIMARY
      KEY</code>
</p>
<p>
<code class="literal">&lt;unique column list&gt; ::= &lt;column name
      list&gt;</code>
</p>
<p>A unique constraint is specified on a single column or on multiple
      columns. On each set of columns taken together, only one UNIQUE
      constraint can be specified. Each column of a PRIMARY KEY constraint has
      an implicit NOT NULL constraint.</p>
<p>If <code class="literal">UNIQUE( VALUE )</code> is specified, the
      constraint created on all columns of the table.</p>
<a name="N110DC" class="indexterm"></a>
<p>
<span class="bold"><strong>FOREIGN KEY</strong></span>
</p>
<p>
<span class="emphasis"><em>referential constraint
      definition</em></span>
</p>
<p>
<code class="literal">&lt;referential constraint definition&gt; ::= FOREIGN
      KEY &lt;left paren&gt; &lt;referencing columns&gt; &lt;right paren&gt;
      &lt;references specification&gt;</code>
</p>
<p>
<code class="literal">&lt;references specification&gt; ::= REFERENCES
      &lt;referenced table and columns&gt; [ MATCH &lt;match type&gt; ] [
      &lt;referential triggered action&gt; ]</code>
</p>
<p>
<code class="literal">&lt;match type&gt; ::= FULL | PARTIAL |
      SIMPLE</code>
</p>
<p>
<code class="literal">&lt;referencing columns&gt; ::= &lt;reference column
      list&gt;</code>
</p>
<p>
<code class="literal">&lt;referenced table and columns&gt; ::= &lt;table
      name&gt; [ &lt;left paren&gt; &lt;reference column list&gt; &lt;right
      paren&gt; ]</code>
</p>
<p>
<code class="literal">&lt;reference column list&gt; ::= &lt;column name
      list&gt;</code>
</p>
<p>
<code class="literal">&lt;referential triggered action&gt; ::= &lt;update
      rule&gt; [ &lt;delete rule&gt; ] | &lt;delete rule&gt; [ &lt;update
      rule&gt; ]</code>
</p>
<p>
<code class="literal">&lt;update rule&gt; ::= ON UPDATE &lt;referential
      action&gt;</code>
</p>
<p>
<code class="literal">&lt;delete rule&gt; ::= ON DELETE &lt;referential
      action&gt;</code>
</p>
<p>
<code class="literal">&lt;referential action&gt; ::= CASCADE | SET NULL |
      SET DEFAULT | RESTRICT | NO ACTION</code>
</p>
<p>A referential constraint allows links to be established between
      the rows of two tables. The specified list of <code class="literal">&lt;referencing
      columns&gt;</code> corresponds one by one to the columns of the
      specified list of <code class="literal">&lt;referenced columns&gt;</code> in
      another table (or sometimes in the same table). For each row in the
      table, a row must exist in the referenced table with equivalent values
      in the two column lists. There must exist a single unique constraint in
      the referenced table on all the <code class="literal">&lt;referenced
      columns&gt;</code>.</p>
<p>The <code class="literal">[ MATCH match type ]</code> clause is optional and
      has an effect only on multi-column foreign keys and only on rows
      containing at least a NULL in one of the <code class="literal">&lt;referencing
      columns&gt;</code>. If the clause is not specified, MATCH SIMPLE is
      the default. If <code class="literal">MATCH SIMPLE</code> is specified, then any
      NULL means the row can exist (without a corresponding row in the
      referenced table). If <code class="literal">MATCH FULL</code> is specified then
      either all the column values must be NULL or none of them.
      <code class="literal">MATCH PARTIAL</code> allows any NULL but the non NULL values
      must match those of a row in the referenced table. HyperSQL does not
      support <code class="literal">MATCH PARTIAL</code>.</p>
<p>Referential actions are specified with ON UPDATE and ON DELETE
      clauses. These actions take place when a row in the referenced table
      (the parent table) has referencing rows in the referencing table and it
      is deleted or modified with any SQL statement. The default is NO ACTION.
      This means the SQL statement that causes the DELETE or UPDATE is
      terminated with an exception. The RESTRICT option is similar and works
      exactly the same without deferrable constraints (which are not allowed
      by HyperSQL). The other three options, CASCADE, SET NULL and SET DEFAULT
      all allow the DELETE or UPDATE statement to complete. With DELETE
      statements the CASCADE option results in the referencing rows to be
      deleted. With UPDATE statements, the changes to the values of the
      referenced columns are copied to the referencing rows. With both DELETE
      or UPDATE statement, the SET NULL option results in the columns of the
      referencing rows to be set to NULL. Similarly, the SET DEFAULT option
      results in the columns of the referencing rows to be set to their
      default values.</p>
<a name="N11127" class="indexterm"></a>
<p>
<span class="bold"><strong>CHECK</strong></span>
</p>
<p>
<span class="emphasis"><em>check constraint definition</em></span>
</p>
<p>
<code class="literal">&lt;check constraint definition&gt; ::= CHECK &lt;left
      paren&gt; &lt;search condition&gt; &lt;right
      paren&gt;</code>
</p>
<p>A CHECK constraint can exist for a TABLE or for a DOMAIN. The
      <code class="literal">&lt;search condition&gt;</code> evaluates to an SQL BOOLEAN
      value for each row of the table. Within the <code class="literal">&lt;search
      condition&gt;</code> all columns of the table row can be referenced.
      For all rows of the table, the <code class="literal">&lt;search
      condition&gt;</code> evaluates to TRUE or UNKNOWN. When a new row is
      inserted, or an existing row is updated, the <code class="literal">&lt;search
      condition&gt;</code> is evaluated and if it is FALSE, the insert or
      update fails.</p>
<p>A CHECK constraint for a DOMAIN is similar. In its
      <code class="literal">&lt;search condition&gt;</code>, the term VALUE is used to
      represents the value to which the DOMAIN applies.</p>
<div class="informalexample">
<pre class="programlisting"> CREATE TABLE t (a VARCHAR(20) CHECK (a IS NOT NULL AND CHARACTER_LENGTH(a) &gt; 2))
</pre>
</div>
<p>The search condition of a CHECK constraint cannot contain any
      function that is not deterministic. A check constraint is a data
      integrity constraint, therefore it must hold with respect to the rest of
      the data in the database. It cannot use values that are temporal or
      ephemeral. For example CURRENT_USER is a function that returns different
      values depending on who is using the database, or CURRENT_DATE changes
      day-to-day. Some temporal expressions are retrospectively deterministic
      and are allowed in check constraints. For example, (CHECK VALUE &lt;
      CURRENT_DATE) is valid, because CURRENT_DATE will not move backwards in
      time, but (CHECK VALUE &gt; CURRENT_DATE) is not acceptable.</p>
<p>If you want to enforce the condition that a date value that is
      inserted into the database belongs to the future (at the time of
      insertion), or any similar constraint, then use a TRIGGER with the
      desired condition.</p>
<a name="N11150" class="indexterm"></a>
<p>
<span class="bold"><strong>DROP TABLE</strong></span>
</p>
<p>
<span class="emphasis"><em>drop table statement</em></span>
</p>
<p>
<code class="literal">&lt;drop table statement&gt; ::= DROP TABLE [ IF
      EXISTS ] &lt;table name&gt; [ IF EXISTS ] &lt;drop
      behavior&gt;</code>
</p>
<p>Destroy a table. The default drop behaviour is RESTRICT and will
      cause the statement to fail if there is any view, routine or foreign key
      constraint that references the table. If <code class="literal">&lt;drop
      behavior&gt;</code> is <code class="literal">CASCADE</code>, it causes all
      schema objects that reference the table to drop. Referencing views are
      dropped. In the case of foreign key constraints that reference the
      table, the constraint is dropped, rather than the TABLE or DOMAIN that
      contains it.</p>
</div>
<div class="section" title="Table Manipulation">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dbc_table_manupulation"></a>Table Manipulation</h3>
</div>
</div>
</div>
<p>Table manipulation statements change the attributes of tables or
      modify the objects such as columns and constraints.</p>
<a name="N1116D" class="indexterm"></a>
<p>
<span class="bold"><strong>SET TABLE CLUSTERED</strong></span>
</p>
<p>
<span class="emphasis"><em>set table clustered property</em></span>
</p>
<p>
<code class="literal">&lt;set table clustered statement&gt; ::= SET TABLE
      &lt;table name&gt; CLUSTERED ON &lt;left paren&gt; &lt;column name
      list&gt; &lt;right paren&gt;</code>
</p>
<p>Set the row clustering property of a table. The &lt;column name
      list&gt; is a list of column names that must correspond to the columns
      of an existing PRIMARY KEY, UNIQUE or FOREIGN KEY index, or to the
      columns of a user defined index. This statement is only valid for CACHED
      or TEXT tables.</p>
<p>Tables rows are stored in the database files as they are created,
      sometimes at the end of the file, sometimes in the middle of the file.
      After a CHECKPOINT DEFRAG or SHUTDOWN COMPACT, the rows are reordered
      according to the primary key of the table, or if there is no primary
      key, in no particular order.</p>
<p>When several consecutive rows of a table are retrieved during
      query execution it is more efficient to retrieve rows that are stored
      adjacent to one another. After executing this command, nothing changes
      until a CHECKPOINT DEFRAG or SHUTDOWN COMPACT or SHUTDOWN SCRIPT is
      performed. After these operations, the rows are stored in the specified
      clustered order. The property is stored in the database and applies to
      all future reordering of rows. Note that if extensive inserts or updates
      are performed on the tables, the rows will get out of order until the
      next reordering.</p>
<a name="N11182" class="indexterm"></a>
<p>
<span class="bold"><strong>SET TABLE TYPE</strong></span>
</p>
<p>
<span class="emphasis"><em>set table type</em></span>
</p>
<p>
<code class="literal">&lt;set table type statement&gt; ::= SET TABLE
      &lt;table name&gt; TYPE { MEMORY | CACHED }</code>
</p>
<p>Changes the storage type of an existing table between CACHED
      and MEMORY types.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<a name="N11195" class="indexterm"></a>
<p>
<span class="bold"><strong>SET TABLE
      writeability</strong></span>
</p>
<p>
<span class="emphasis"><em>set table write property</em></span>
</p>
<p>
<code class="literal">&lt;set table read only statement&gt; ::= SET TABLE
      &lt;table name&gt; { READ ONLY | READ WRITE }</code>
</p>
<p>Set the writeability property of a table. Tables are writeable
      by default. This statement can be used to change the property between
      <code class="literal">READ ONLY</code> and <code class="literal">READ WRITE</code>. This is
      a feature of HyperSQL.</p>
<a name="N111AC" class="indexterm"></a>
<p>
<span class="bold"><strong>SET TABLE SOURCE</strong></span>
</p>
<p>
<span class="emphasis"><em>set table source statement</em></span>
</p>
<p>
<code class="literal">&lt;set table source statement&gt; ::= SET TABLE
      &lt;table name&gt; SOURCE &lt;file and options&gt;
      [DESC]</code>
</p>
<p>
<code class="literal">&lt;file and options&gt;::= &lt;doublequote&gt;
      &lt;file path&gt; [&lt;semicolon&gt; &lt;property&gt;...]
      &lt;doublequote&gt; </code>
</p>
<p>Set the text source for a text table. This statement cannot be
      used for tables that are not defined as TEXT TABLE.</p>
<div class="variablelist" title="Supported Properties">
<p class="title">
<b>Supported Properties</b>
</p>
<table border="0">
<col valign="top" align="left">
<tbody>
<tr>
<td>
<p>
<span class="term">quoted = { true | false }</span>
</p>
</td><td>
<p>default is true. If false, treats double quotes as normal
            characters</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="term">all_quoted = { true | false }</span>
</p>
</td><td>
<p>default is false. If true, adds double quotes around all
            fields.</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="term">encoding = &lt;encoding name&gt;</span>
</p>
</td><td>
<p>character encoding for text and character fields, for
            example, encoding=UTF-8. UTF-16 cannot be used.</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="term">ignore_first = { true | false }</span>
</p>
</td><td>
<p>default is false. If true ignores the first line of the
            file</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="term">cache_rows= &lt;numeric value&gt;</span>
</p>
</td><td>
<p>rows of the text file in the cache. Default is 1000
            rows</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="term">cache_size = &lt;numeric value&gt;r</span>
</p>
</td><td>
<p>total size of the row in the cache. Default is 100
            KB.</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="term">cache_scale= &lt;numeric value&gt; and cache_size_scale =
          &lt;numeric value&gt;</span>
</p>
</td><td>
<p>deprecated properties, replaced by cached_rows and
            cache_size properties above.</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="term">fs = &lt;unquoted character&gt;</span>
</p>
</td><td>
<p>field separator</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="term">vs = &lt;unquoted character&gt;</span>
</p>
</td><td>
<p>varchar separator</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="variablelist" title="Special indicators for HyperSQL Text Table separators">
<p class="title">
<b>Special indicators for HyperSQL Text Table separators</b>
</p>
<table border="0">
<col valign="top" align="left">
<tbody>
<tr>
<td>
<p>
<span class="term">\semi</span>
</p>
</td><td>
<p>semicolon</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="term">\quote</span>
</p>
</td><td>
<p>quote</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="term">\space</span>
</p>
</td><td>
<p>space character</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="term">\apos</span>
</p>
</td><td>
<p>apostrophe</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="term">\n</span>
</p>
</td><td>
<p>newline - Used as an end anchor (like $ in regular
            expressions)</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="term">\r</span>
</p>
</td><td>
<p>carriage return</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="term">\t</span>
</p>
</td><td>
<p>tab</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="term">\\</span>
</p>
</td><td>
<p>backslash</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="term">\u####</span>
</p>
</td><td>
<p>a Unicode character specified in hexadecimal</p>
</td>
</tr>
</tbody>
</table>
</div>
<p>In the example below, the text source of the table is set to
      "myfile", the field separator to the pipe symbol, and the varchar
      separator to the tilde symbol.</p>
<pre class="programlisting"> SET TABLE mytable SOURCE 'myfile;fs=|;vs=.;vs=~'</pre>
<p>Only a user with the DBA role can execute this
      statement.</p>
<a name="N11238" class="indexterm"></a>
<p>
<span class="bold"><strong>SET TABLE SOURCE
      HEADER</strong></span>
</p>
<p>
<span class="emphasis"><em>set table source header
      statement</em></span>
</p>
<p>
<code class="literal">&lt;set table source header statement&gt; ::= SET
      TABLE &lt;table name&gt; SOURCE HEADER &lt;header
      string&gt;</code>
</p>
<p>Set the header for the text source for a text table. If this
      command is used, the <code class="literal">&lt;header string&gt;</code> is used as
      the first line of the source file of the text table. This line is not
      part of the table data. Only a user with the DBA role can execute this
      statement.</p>
<a name="N1124C" class="indexterm"></a>
<p>
<span class="bold"><strong>SET TABLE SOURCE
      on-off</strong></span>
</p>
<p>
<span class="emphasis"><em>set table source on-off
      statement</em></span>
</p>
<p>
<code class="literal">&lt;set table source on-off statement&gt; ::= SET
      TABLE &lt;table name&gt; SOURCE { ON | OFF } </code>
</p>
<p>Attach or detach a text table from its text source. This
      command does not change the properties or the name of the file that is
      the source of a text table. When OFF is specified, the command detaches
      the table from its source and closes the file for the source. In this
      state, it is not possible to read or write to the table. This allows the
      user to replace the file with a different file, or delete it. When ON is
      specified, the source file is read. Only a user with the DBA role can
      execute this statement</p>
<a name="N1125D" class="indexterm"></a>
<p>
<span class="bold"><strong>ALTER TABLE</strong></span>
</p>
<p>
<span class="emphasis"><em>alter table statement</em></span>
</p>
<p>
<code class="literal">&lt;alter table statement&gt; ::= ALTER TABLE
      &lt;table name&gt; &lt;alter table action&gt;</code>
</p>
<p>
<code class="literal">&lt;alter table action&gt; ::= &lt;add column
      definition&gt; | &lt;alter column definition&gt; | &lt;drop column
      definition&gt; | &lt;add table constraint definition&gt; | &lt;drop
      table constraint definition&gt;</code>
</p>
<p>Change the definition of a table. Specific types of this
      statement are covered below.</p>
<a name="N11271" class="indexterm"></a>
<p>
<span class="bold"><strong>ADD COLUMN</strong></span>
</p>
<p>
<span class="emphasis"><em>add column definition</em></span>
</p>
<p>
<code class="literal">&lt;add column definition&gt; ::= ADD [ COLUMN ]
      &lt;column definition&gt; [ BEFORE &lt;other column name&gt;
      ]</code>
</p>
<p>Add a column to an existing table. The <code class="literal">&lt;column
      definition&gt;</code> is specified the same way as it is used in
      <code class="literal">&lt;table definition&gt;</code>. HyperSQL allows the use of
      <code class="literal">[ BEFORE &lt;other column name&gt; ]</code> to specify at
      which position the new column is added to the table.</p>
<p>If the table contains rows, the new column must have a
      <code class="literal">&lt;default clause&gt;</code> or use one of the forms of
      GENERATED. The column values for each row is then filled with the result
      of the <code class="literal">&lt;default clause&gt;</code> or the generated
      value.</p>
<a name="N11293" class="indexterm"></a>
<p>
<span class="bold"><strong>DROP COLUMN</strong></span>
</p>
<p>
<span class="emphasis"><em>drop column definition</em></span>
</p>
<p>
<code class="literal">&lt;drop column definition&gt; ::= DROP [ COLUMN ]
      &lt;column name&gt; &lt;drop behavior&gt;</code>
</p>
<p>Destroy a column of a base table. The <code class="literal">&lt;drop
      behavior&gt;</code> is either <code class="literal">RESTRICT</code> or
      <code class="literal">CASCADE</code>. If the column is referenced in a table
      constraint that references other columns as well as this column, or if
      the column is referenced in a VIEW, or the column is referenced in a
      TRIGGER, then the statement will fail if <code class="literal">RESTRICT</code> is
      specified. If <code class="literal">CASCADE</code> is specified, then any
      CONSTRAINT, VIEW or TRIGGER object that references the column is dropped
      with a cascading effect.</p>
<a name="N112B3" class="indexterm"></a>
<p>
<span class="bold"><strong>ADD CONSTRAINT</strong></span>
</p>
<p>
<span class="emphasis"><em>add table constraint definition</em></span>
</p>
<p>
<code class="literal">&lt;add table constraint definition&gt; ::= ADD
      &lt;table constraint definition&gt;</code>
</p>
<p>Add a constraint to a table. The existing rows of the table
      must conform to the added constraint, otherwise the statement will not
      succeed.</p>
<a name="N112C4" class="indexterm"></a>
<p>
<span class="bold"><strong>DROP CONSTRAINT</strong></span>
</p>
<p>
<span class="emphasis"><em>drop table constraint definition</em></span>
</p>
<p>
<code class="literal">&lt;drop table constraint definition&gt; ::= DROP
      CONSTRAINT &lt;constraint name&gt; &lt;drop
      behavior&gt;</code>
</p>
<p>Destroy a constraint on a table. The <code class="literal">&lt;drop
      behavior&gt;</code> has an effect only on UNIQUE and PRIMARY KEY
      constraints. If such a constraint is referenced by a FOREIGN KEY
      constraint, the FOREIGN KEY constraint will be dropped if
      <code class="literal">CASCADE</code> is specified. If the columns of such a
      constraint are used in a GROUP BY clause in the query expression of a
      VIEW or another kind of schema object, and a functional dependency
      relationship exists between these columns and the other columns in that
      query expression, then the VIEW or other schema object will be dropped
      when <code class="literal">CASCADE</code> is specified.</p>
<a name="N112DE" class="indexterm"></a>
<p>
<span class="bold"><strong>ALTER COLUMN</strong></span>
</p>
<p>
<span class="emphasis"><em>alter column definition</em></span>
</p>
<p>
<code class="literal">&lt;alter column definition&gt; ::= ALTER [ COLUMN ]
      &lt;column name&gt; &lt;alter column action&gt;</code>
</p>
<p>
<code class="literal">&lt;alter column action&gt; ::= &lt;set column default
      clause&gt; | &lt;drop column default clause&gt; | &lt;alter column data
      type clause&gt; | &lt;alter identity column specification&gt; |
      &lt;alter column nullability&gt; | &lt;alter column name&gt; | &lt;add
      column identity specification&gt; | &lt;drop column identity
      specification&gt;</code>
</p>
<p>Change a column and its definition. Specific types of this
      statement are covered below. See also the RENAME statement
      above.</p>
<a name="N112F2" class="indexterm"></a>
<p>
<span class="bold"><strong>SET DEFAULT</strong></span>
</p>
<p>
<span class="emphasis"><em>set column default clause</em></span>
</p>
<p>
<code class="literal">&lt;set column default clause&gt; ::= SET &lt;default
      clause&gt;</code>
</p>
<p>Set the default clause for a column. This can be used if the
      column is not defined as GENERATED.</p>
<a name="N11303" class="indexterm"></a>
<p>
<span class="bold"><strong>DROP DEFAULT</strong></span>
</p>
<p>
<span class="emphasis"><em>drop column default clause</em></span>
</p>
<p>
<code class="literal">&lt;drop column default clause&gt; ::= DROP
      DEFAULT</code>
</p>
<p>Drop the default clause from a column.</p>
<a name="N11314" class="indexterm"></a>
<p>
<span class="bold"><strong>SET DATA TYPE</strong></span>
</p>
<p>
<span class="emphasis"><em>alter column data type clause</em></span>
</p>
<p>
<code class="literal">&lt;alter column data type clause&gt; ::= SET DATA
      TYPE &lt;data type&gt;</code>
</p>
<p>Change the declared type of a column. The latest SQL Standard
      allows only changes to type properties such as maximum length,
      precision, or scale, and only changes that cause the property to
      enlarge. HyperSQL allows changing the type if all the existing values
      can be cast into the new type without string truncation or loss of
      significant digits.</p>
<a name="N11325" class="indexterm"></a>
<p>
<span class="bold"><strong>alter column add identity
      generator</strong></span>
</p>
<p>
<span class="emphasis"><em>alter column add identity
      generator</em></span>
</p>
<p>
<code class="literal">&lt;add column identity generator&gt; ::= &lt;identity
      column specification&gt;</code>
</p>
<p>Adds an identity specification to the column. The type of the
      column must be an integral type and the existing values must not include
      nulls. This option is specific to HyperSQL</p>
<pre class="programlisting"> ALTER TABLE mytable ALTER COLUMN id GENERATED ALWAYS AS IDENTITY (START WITH 20000)</pre>
<a name="N11338" class="indexterm"></a>
<p>
<span class="bold"><strong>alter column identity
      generator</strong></span>
</p>
<p>
<span class="emphasis"><em>alter identity column
      specification</em></span>
</p>
<p>
<code class="literal">&lt;alter identity column specification&gt; ::=
      &lt;alter identity column option&gt;...</code>
</p>
<p>
<code class="literal">&lt;alter identity column option&gt; ::= &lt;alter
      sequence generator restart option&gt; | SET &lt;basic sequence generator
      option&gt;</code>
</p>
<p>Change the properties of an identity column. This command is
      similar to the commands used for changing the properties of named
      SEQUENCE objects discussed earlier and can use the same options.</p>
<pre class="programlisting"> ALTER TABLE mytable ALTER COLUMN id RESTART WITH 1000
 ALTER TABLE mytable ALTER COLUMN id SET INCREMENT BY 5
</pre>
<a name="N1134E" class="indexterm"></a>
<p>
<span class="bold"><strong>DROP GENERATED</strong></span>
</p>
<p>
<span class="emphasis"><em>drop column identity generator</em></span>
</p>
<p>
<code class="literal">&lt;drop column identity specification&gt; ::= DROP
      GENERATED</code>
</p>
<p>Removes the identity generator from a column. After executing this
      statement, the column values are no longer generated automatically. This
      option is specific to HyperSQL</p>
<pre class="programlisting">  ALTER TABLE mytable ALTER COLUMN id DROP GENERATED
</pre>
<a name="N11361" class="indexterm"></a>
<p>
<span class="bold"><strong>SET [ NOT ] NULL</strong></span>
</p>
<p>
<span class="emphasis"><em>alter column nullability</em></span>
</p>
<p>
<code class="literal">&lt;alter column nullability&gt; ::= SET [ NOT ]
      NULL</code>
</p>
<p>Adds or removes a NOT NULL constraint from a column. This
      option is specific to HyperSQL</p>
</div>
<div class="section" title="View Creation and Manipulation">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dbc_view_creation"></a>View Creation and Manipulation</h3>
</div>
</div>
</div>
<a name="N11376" class="indexterm"></a>
<p>
<span class="bold"><strong>CREATE VIEW</strong></span>
</p>
<p>
<span class="emphasis"><em>view definition</em></span>
</p>
<p>
<code class="literal">&lt;view definition&gt; ::= CREATE VIEW &lt;table
      name&gt; &lt;view specification&gt; AS &lt;query expression&gt; [ WITH [
      CASCADED | LOCAL ] CHECK OPTION ]</code>
</p>
<p>
<code class="literal">&lt;view specification&gt; ::= [ &lt;left paren&gt;
      &lt;view column list&gt; &lt;right paren&gt; ]</code>
</p>
<p>
<code class="literal">&lt;view column list&gt; ::= &lt;column name
      list&gt;</code>
</p>
<p>Define a view. The <code class="literal">&lt;query expression&gt;</code>
      is a SELECT or similar statement. The <code class="literal">&lt;view column
      list&gt;</code> is the list of unique names for the columns of the
      view. The number of columns in the <code class="literal">&lt;view column
      list&gt;</code> must match the number of columns returned by the
      <code class="literal">&lt;query expression&gt;</code>. If <code class="literal">&lt;view column
      list&gt;</code> is not specified, then the columns of the
      <code class="literal">&lt;query expression&gt;</code> should have unique names and
      are used as the names of the view column.</p>
<p>Some views are updatable. As covered elsewhere, an updatable
      view is based on a single table or updatable view. For updatable views,
      the optional <code class="literal">CHECK OPTION</code> clause can be specified. If
      this option is specified, then if a row of the view is updated or a new
      row is inserted into the view, then it should contain such values that
      the row would be included in the view after the change. If <code class="literal">WITH
      CASCADED CHECK OPTION</code> is specified, then if the
      <code class="literal">&lt;query expression&gt;</code> of the view references
      another view, then the search condition of the underlying view should
      also be satisfied by the update or insert operation.</p>
<a name="N113AA" class="indexterm"></a>
<p>
<span class="bold"><strong>DROP VIEW</strong></span>
</p>
<p>
<span class="emphasis"><em>drop view statement</em></span>
</p>
<p>
<code class="literal">&lt;drop view statement&gt; ::= DROP VIEW [ IF EXISTS
      ] &lt;table name&gt; [ IF EXISTS ] &lt;drop
      behavior&gt;</code>
</p>
<p>Destroy a view. The <code class="literal">&lt;drop behavior&gt;</code> is
      similar to dropping a table.</p>
<a name="N113BE" class="indexterm"></a>
<p>
<span class="bold"><strong>ALTER VIEW</strong></span>
</p>
<p>
<span class="emphasis"><em>alter view statement</em></span>
</p>
<p>
<code class="literal">&lt;alter view statement&gt; ::= ALTER VIEW &lt;table
      name&gt; &lt;view specification&gt; AS &lt;query expression&gt; [ WITH [
      CASCADED | LOCAL ] CHECK OPTION ]</code>
</p>
<p>Alter a view. The statement is otherwise identical to CREATE VIEW.
      The new definition replaces the old. If there are database objects such
      as routines or views that reference the view, then these objects are
      recompiled with the new view definition. If the new definition is not
      compatible, the statement fails.</p>
</div>
<div class="section" title="Domain Creation and Manipulation">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dbc_domain_creation"></a>Domain Creation and Manipulation</h3>
</div>
</div>
</div>
<a name="N113D3" class="indexterm"></a>
<p>
<span class="bold"><strong>CREATE DOMAIN</strong></span>
</p>
<p>
<span class="emphasis"><em>domain definition</em></span>
</p>
<p>
<code class="literal">&lt;domain definition&gt; ::= CREATE DOMAIN &lt;domain
      name&gt; [ AS ] &lt;predefined type&gt; [ &lt;default clause&gt; ] [
      &lt;domain constraint&gt;... ] [ &lt;collate clause&gt;
      ]</code>
</p>
<p>
<code class="literal">&lt;domain constraint&gt; ::= [ &lt;constraint name
      definition&gt; ] &lt;check constraint definition&gt; [ &lt;constraint
      characteristics&gt; ]</code>
</p>
<p>Define a domain. Although a DOMAIN is not strictly a type in the
      SQL Standard, it can be informally considered as a type. A DOMAIN is
      based on a <code class="literal">&lt;predefined type&gt;</code>, which is a base
      type defined by the Standard. It can have a <code class="literal">&lt;default
      clause&gt;</code>, similar to a column default clause. It can also
      have one or more CHECK constraints which limit the values that can be
      assigned to a column or variable that has the DOMAIN as its type.</p>
<div class="informalexample">
<pre class="programlisting"> CREATE DOMAIN valid_string AS VARCHAR(20) DEFAULT 'NO VALUE' CHECK (value IS NOT NULL AND CHARACTER_LENGTH(value) &gt; 2) 
</pre>
</div>
<a name="N113F0" class="indexterm"></a>
<p>
<span class="bold"><strong>ALTER DOMAIN</strong></span>
</p>
<p>
<span class="emphasis"><em>alter domain statement</em></span>
</p>
<p>
<code class="literal">&lt;alter domain statement&gt; ::= ALTER DOMAIN
      &lt;domain name&gt; &lt;alter domain action&gt;</code>
</p>
<p>
<code class="literal">&lt;alter domain action&gt; ::= &lt;set domain default
      clause&gt; | &lt;drop domain default clause&gt; | &lt;add domain
      constraint definition&gt; | &lt;drop domain constraint
      definition&gt;</code>
</p>
<p>Change a domain and its definition.</p>
<a name="N11404" class="indexterm"></a>
<p>
<span class="bold"><strong>SET DEFAULT</strong></span>
</p>
<p>
<span class="emphasis"><em>set domain default clause</em></span>
</p>
<p>
<code class="literal">&lt;set domain default clause&gt; ::= SET &lt;default
      clause&gt;</code>
</p>
<p>Set the default value in a domain.</p>
<a name="N11415" class="indexterm"></a>
<p>
<span class="bold"><strong>DROP DEFAULT</strong></span>
</p>
<p>
<span class="emphasis"><em>drop domain default clause</em></span>
</p>
<p>
<code class="literal">&lt;drop domain default clause&gt; ::= DROP
      DEFAULT</code>
</p>
<p>Remove the default clause of a domain.</p>
<a name="N11426" class="indexterm"></a>
<p>
<span class="bold"><strong>ADD CONSTRAINT</strong></span>
</p>
<p>
<span class="emphasis"><em>add domain constraint definition</em></span>
</p>
<p>
<code class="literal">&lt;add domain constraint definition&gt; ::= ADD
      &lt;domain constraint&gt;</code>
</p>
<p>Add a constraint to a domain.</p>
<a name="N11437" class="indexterm"></a>
<p>
<span class="bold"><strong>DROP CONSTRAINT</strong></span>
</p>
<p>
<span class="emphasis"><em>drop domain constraint
      definition</em></span>
</p>
<p>
<code class="literal">&lt;drop domain constraint definition&gt; ::= DROP
      CONSTRAINT &lt;constraint name&gt;</code>
</p>
<p>Destroy a constraint on a domain. If the <code class="literal">&lt;drop
      behavior&gt;</code> is <code class="literal">CASCADE</code>, and the constraint
      is a UNIQUE constraint which is referenced by a FOREIGN KEY constraint
      on another table, then the FOREIGN KEY constraint is also
      dropped.</p>
<a name="N1144E" class="indexterm"></a>
<p>
<span class="bold"><strong>DROP DOMAIN</strong></span>
</p>
<p>
<span class="emphasis"><em>drop domain statement</em></span>
</p>
<p>
<code class="literal">&lt;drop domain statement&gt; ::= DROP DOMAIN
      &lt;domain name&gt; &lt;drop behavior&gt;</code>
</p>
<p>Destroy a domain. If <code class="literal">&lt;drop behavior&gt;</code> is
      <code class="literal">CASCADE</code>, it works differently from most other
      objects. If a table features a column of the specified DOMAIN, the
      column survives and inherits the DEFAULT CLAUSE, and the CHECK
      CONSTRAINT of the DOMAIN.</p>
</div>
<div class="section" title="Trigger Creation">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dbc_trigger_creation"></a>Trigger Creation</h3>
</div>
</div>
</div>
<a name="N11469" class="indexterm"></a>
<p>
<span class="bold"><strong>CREATE TRIGGER</strong></span>
</p>
<p>
<span class="emphasis"><em>trigger definition</em></span>
</p>
<p>
<code class="literal">&lt;trigger definition&gt; ::= CREATE TRIGGER
      &lt;trigger name&gt; &lt;trigger action time&gt; &lt;trigger event&gt;
      ON &lt;table name&gt; [ REFERENCING &lt;transition table or variable
      list&gt; ] &lt;triggered action&gt;</code>
</p>
<p>
<code class="literal">&lt;trigger action time&gt; ::= BEFORE | AFTER |
      INSTEAD OF</code>
</p>
<p>
<code class="literal">&lt;trigger event&gt; ::= INSERT | DELETE | UPDATE [
      OF &lt;trigger column list&gt; ]</code>
</p>
<p>
<code class="literal">&lt;trigger column list&gt; ::= &lt;column name
      list&gt;</code>
</p>
<p>
<code class="literal">&lt;triggered action&gt; ::= [ FOR EACH { ROW |
      STATEMENT } ] [ &lt;triggered when clause&gt; ] &lt;triggered SQL
      statement&gt;</code>
</p>
<p>
<code class="literal">&lt;triggered when clause&gt; ::= WHEN &lt;left
      paren&gt; &lt;search condition&gt; &lt;right
      paren&gt;</code>
</p>
<p>
<code class="literal">&lt;triggered SQL statement&gt; ::= &lt;SQL procedure
      statement&gt; | BEGIN ATOMIC { &lt;SQL procedure statement&gt;
      &lt;semicolon&gt; }... END | [QUEUE &lt;integer literal&gt;] [NOWAIT]
      CALL &lt;HSQLDB trigger class FQN&gt;</code>
</p>
<p>
<code class="literal">&lt;transition table or variable list&gt; ::=
      &lt;transition table or variable&gt;...</code>
</p>
<p>
<code class="literal">&lt;transition table or variable&gt; ::= OLD [ ROW ] [
      AS ] &lt;old transition variable name&gt; | NEW [ ROW ] [ AS ] &lt;new
      transition variable name&gt; | OLD TABLE [ AS ] &lt;old transition table
      name&gt; | NEW TABLE [ AS ] &lt;new transition table
      name&gt;</code>
</p>
<p>
<code class="literal">&lt;old transition table name&gt; ::= &lt;transition
      table name&gt;</code>
</p>
<p>
<code class="literal">&lt;new transition table name&gt; ::= &lt;transition
      table name&gt;</code>
</p>
<p>
<code class="literal">&lt;transition table name&gt; ::=
      &lt;identifier&gt;</code>
</p>
<p>
<code class="literal">&lt;old transition variable name&gt; ::=
      &lt;correlation name&gt;</code>
</p>
<p>
<code class="literal">&lt;new transition variable name&gt; ::=
      &lt;correlation name&gt;</code>
</p>
<p>Trigger definition is a relatively complex statement. The
      combination of <code class="literal">&lt;trigger action time&gt;</code> and
      <code class="literal">&lt;trigger event&gt;</code> determines the type of the
      trigger. Examples include BEFORE DELETE, AFTER UPDATE, INSTEAD OF
      INSERT. If the optional <code class="literal">[ OF &lt;trigger column list&gt;
      ]</code> is specified for an UPDATE trigger, then the trigger is
      activated only if one of the columns that is in the <code class="literal">&lt;trigger
      column list&gt;</code> is specified in the UPDATE statement that
      activates the trigger.</p>
<p>If a trigger is <code class="literal">FOR EACH ROW</code>, which is the
      default option, then the trigger is activated for each row of the table
      that is affected by the execution of an SQL statement. Otherwise, it is
      activated once only per statement execution. In the first case, there is
      a before and after state for each row. For UPDATE triggers, both before
      and after states exist, representing the row before the update, and
      after the update. For DELETE, triggers, there is only a before state.
      For INSERT triggers, there is only an after state. If a trigger is
      <code class="literal">FOR EACH STATEMENT</code>, then a transient table is created
      containing all the rows for the before state and another transient table
      is created for the after state.</p>
<p>The <code class="literal">[ REFERENCING &lt;transition table or variable&gt;
      ]</code> is used to give a name to the before and after data row or
      table. This name can be referenced in the <code class="literal">&lt;SQL procedure
      statement&gt;</code> to access the data.</p>
<p>The optional <code class="literal">&lt;triggered when clause&gt;</code> is a
      search condition, similar to the search condition of a DELETE or UPDATE
      statement. If the search condition is not TRUE for a row, then the
      trigger is not activated for that row.</p>
<p>The <code class="literal">&lt;SQL procedure statement&gt;</code> is limited
      to INSERT, DELETE, UPDATE and MERGE statements.</p>
<p>The <code class="literal">&lt;HSQLDB trigger class FQN&gt;</code> is a
      delimited identifier that contains the fully qualified name of a Java
      class that implements the <code class="classname">org.hsqldb.Trigger</code>
      interface.</p>
<p>HyperSQL do not yet allow the use of OLD TABLE or NEW TABLE in
      statement level trigger definitions.</p>
<a name="N114D1" class="indexterm"></a>
<p>
<span class="bold"><strong>DROP TRIGGER</strong></span>
</p>
<p>
<span class="emphasis"><em>drop trigger statement</em></span>
</p>
<p>
<code class="literal">&lt;drop trigger statement&gt; ::= DROP TRIGGER
      &lt;trigger name&gt;</code>
</p>
<p>Destroy a trigger.</p>
</div>
<div class="section" title="Routine Creation">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dbc_routine_creation"></a>Routine Creation</h3>
</div>
</div>
</div>
<a name="N114E6" class="indexterm"></a>
<p>
<span class="bold"><strong>schema routine</strong></span>
</p>
<p>
<span class="emphasis"><em>SQL-invoked routine</em></span>
</p>
<p>
<code class="literal">&lt;SQL-invoked routine&gt; ::= &lt;schema
      routine&gt;</code>
</p>
<p>
<code class="literal">&lt;schema routine&gt; ::= &lt;schema procedure&gt; |
      &lt;schema function&gt;</code>
</p>
<p>
<code class="literal">&lt;schema procedure&gt; ::= CREATE &lt;SQL-invoked
      procedure&gt;</code>
</p>
<p>
<code class="literal">&lt;schema function&gt; ::= CREATE &lt;SQL-invoked
      function&gt;</code>
</p>
<p>
<code class="literal">&lt;SQL-invoked procedure&gt; ::= PROCEDURE &lt;schema
      qualified routine name&gt; &lt;SQL parameter declaration list&gt;
      &lt;routine characteristics&gt; &lt;routine body&gt;</code>
</p>
<p>
<code class="literal">&lt;SQL-invoked function&gt; ::= { &lt;function
      specification&gt; | &lt;method specification designator&gt; }
      &lt;routine body&gt;</code>
</p>
<p>
<code class="literal">&lt;SQL parameter declaration list&gt; ::= &lt;left
      paren&gt; [ &lt;SQL parameter declaration&gt; [ { &lt;comma&gt; &lt;SQL
      parameter declaration&gt; }... ] ] &lt;right
      paren&gt;</code>
</p>
<p>
<code class="literal">&lt;SQL parameter declaration&gt; ::= [ &lt;parameter
      mode&gt; ] [ &lt;SQL parameter name&gt; ] &lt;parameter type&gt; [
      RESULT ]</code>
</p>
<p>
<code class="literal">&lt;parameter mode&gt; ::= IN | OUT |
      INOUT</code>
</p>
<p>
<code class="literal">&lt;parameter type&gt; ::= &lt;data
      type&gt;</code>
</p>
<p>
<code class="literal">&lt;function specification&gt; ::= FUNCTION &lt;schema
      qualified routine name&gt; &lt;SQL parameter declaration list&gt;
      &lt;returns clause&gt; &lt;routine characteristics&gt; [ &lt;dispatch
      clause&gt; ]</code>
</p>
<p>
<code class="literal">&lt;method specification designator&gt; ::= SPECIFIC
      METHOD &lt;specific method name&gt; | [ INSTANCE | STATIC | CONSTRUCTOR
      ] METHOD &lt;method name&gt; &lt;SQL parameter declaration list&gt; [
      &lt;returns clause&gt; ] FOR &lt;schema-resolved user-defined type
      name&gt;</code>
</p>
<p>
<code class="literal">&lt;routine characteristics&gt; ::= [ &lt;routine
      characteristic&gt;... ]</code>
</p>
<p>
<code class="literal">&lt;routine characteristic&gt; ::= &lt;language
      clause&gt; | &lt;parameter style clause&gt; | SPECIFIC &lt;specific
      name&gt; | &lt;deterministic characteristic&gt; | &lt;SQL-data access
      indication&gt; | &lt;null-call clause&gt; | &lt;returned result sets
      characteristic&gt; | &lt;savepoint level
      indication&gt;</code>
</p>
<p>
<code class="literal">&lt;savepoint level indication&gt; ::= NEW SAVEPOINT
      LEVEL | OLD SAVEPOINT LEVEL</code>
</p>
<p>
<code class="literal">&lt;returned result sets characteristic&gt; ::=
      DYNAMIC RESULT SETS &lt;maximum returned result
      sets&gt;</code>
</p>
<p>
<code class="literal">&lt;parameter style clause&gt; ::= PARAMETER STYLE
      &lt;parameter style&gt;</code>
</p>
<p>
<code class="literal">&lt;dispatch clause&gt; ::= STATIC
      DISPATCH</code>
</p>
<p>
<code class="literal">&lt;returns clause&gt; ::= RETURNS &lt;returns
      type&gt;</code>
</p>
<p>
<code class="literal">&lt;returns type&gt; ::= &lt;returns data type&gt; [
      &lt;result cast&gt; ] | &lt;returns table type&gt;</code>
</p>
<p>
<code class="literal">&lt;returns table type&gt; ::= TABLE &lt;table
      function column list&gt;</code>
</p>
<p>
<code class="literal">&lt;table function column list&gt; ::= &lt;left
      paren&gt; &lt;table function column list element&gt; [ { &lt;comma&gt;
      &lt;table function column list element&gt; }... ] &lt;right
      paren&gt;</code>
</p>
<p>
<code class="literal">&lt;table function column list element&gt; ::=
      &lt;column name&gt; &lt;data type&gt;</code>
</p>
<p>
<code class="literal">&lt;result cast&gt; ::= CAST FROM &lt;result cast from
      type&gt;</code>
</p>
<p>
<code class="literal">&lt;result cast from type&gt; ::= &lt;data type&gt; [
      &lt;locator indication&gt; ]</code>
</p>
<p>
<code class="literal">&lt;returns data type&gt; ::= &lt;data type&gt; [
      &lt;locator indication&gt; ]</code>
</p>
<p>
<code class="literal">&lt;routine body&gt; ::= &lt;SQL routine spec&gt; |
      &lt;external body reference&gt;</code>
</p>
<p>
<code class="literal">&lt;SQL routine spec&gt; ::= [ &lt;rights clause&gt; ]
      &lt;SQL routine body&gt;</code>
</p>
<p>
<code class="literal">&lt;rights clause&gt; ::= SQL SECURITY INVOKER | SQL
      SECURITY DEFINER</code>
</p>
<p>
<code class="literal">&lt;SQL routine body&gt; ::= &lt;SQL procedure
      statement&gt;</code>
</p>
<p>
<code class="literal">&lt;external body reference&gt; ::= EXTERNAL [ NAME
      &lt;external routine name&gt; ] [ &lt;parameter style clause&gt;
      ]</code>
</p>
<p>
<code class="literal">&lt;parameter style&gt; ::= SQL |
      GENERAL</code>
</p>
<p>
<code class="literal">&lt;deterministic characteristic&gt; ::= DETERMINISTIC
      | NOT DETERMINISTIC</code>
</p>
<p>
<code class="literal">&lt;SQL-data access indication&gt; ::= NO SQL |
      CONTAINS SQL | READS SQL DATA | MODIFIES SQL DATA</code>
</p>
<p>
<code class="literal">&lt;null-call clause&gt; ::= RETURNS NULL ON NULL
      INPUT | CALLED ON NULL INPUT</code>
</p>
<p>
<code class="literal">&lt;maximum returned result sets&gt; ::= &lt;unsigned
      integer&gt;</code>
</p>
<p>Define an SQL-invoked routine. A few of the options are not used
      by HyperSQL and have default behaviours. See the <a class="link" href="#sqlroutines-chapt" title="Chapter&nbsp;8.&nbsp;SQL-Invoked Routines">SQL-Invoked Routines</a> chapter for more details of
      various options and examples.</p>
<a name="N11565" class="indexterm"></a>
<p>
<span class="bold"><strong>ALTER routine</strong></span>
</p>
<p>
<span class="emphasis"><em>alter routine statement</em></span>
</p>
<p>
<code class="literal">&lt;alter routine statement&gt; ::= ALTER &lt;specific
      routine designator&gt; [ &lt;alter routine characteristics&gt; ] [
      RESTRICT ] &lt;routine body&gt; </code>
</p>
<p>
<code class="literal">&lt;alter routine characteristics&gt; ::= &lt;alter
      routine characteristic&gt;...</code>
</p>
<p>
<code class="literal">&lt;alter routine characteristic&gt; ::= &lt;language
      clause&gt; | &lt;parameter style clause&gt; | &lt;SQL-data access
      indication&gt; | &lt;null-call clause&gt; | &lt;returned result sets
      characteristic&gt;</code>
</p>
<p>
<code class="literal">&lt;alter routine body&gt; ::= &lt;SQL routine
      body&gt;</code>
</p>
<p>Alter the characteristic and the body of an SQL-invoked routine.
      If RESTRICT is specified and the routine is already used in a a
      different routine or view definition, an exception is raised. Altering
      the routine changes the implementation without changing the parameters.
      Defining recursive SQL/PSM SQL functions is only possible by altering a
      non-recursive routine body. An example is given in the <a class="link" href="#sqlroutines-chapt" title="Chapter&nbsp;8.&nbsp;SQL-Invoked Routines">SQL-Invoked Routines</a> chapter.</p>
<p>An example is given below for a function defined as a Java method,
      then redefined as an SQL function.</p>
<pre class="programlisting"> CREATE FUNCTION zero_pad(x BIGINT, digits INT, maxsize INT)
  RETURNS CHAR VARYING(100)
  SPECIFIC zero_pad_01
  NO SQL DETERMINISTIC
  LANGUAGE JAVA
  EXTERNAL NAME 'CLASSPATH:org.hsqldb.lib.StringUtil.toZeroPaddedString';

 ALTER SPECIFIC ROUTINE zero_pad_01
  LANGUAGE SQL
  BEGIN ATOMIC
  DECLARE str VARCHAR(128);
  SET str = CAST(x AS VARCHAR(128));
  SET str = SUBSTRING('0000000000000' FROM 1 FOR digits - CHAR_LENGTH(str)) + str;
  return str;
  END
</pre>
<a name="N11588" class="indexterm"></a>
<p>
<span class="bold"><strong>DROP</strong></span>
</p>
<p>
<span class="emphasis"><em>drop routine statement</em></span>
</p>
<p>
<code class="literal">&lt;drop routine statement&gt; ::= DROP &lt;specific
      routine designator&gt; &lt;drop behavior&gt;</code>
</p>
<p>Destroy an SQL-invoked routine.</p>
</div>
<div class="section" title="Sequence Creation">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dbc_sequence_creation"></a>Sequence Creation</h3>
</div>
</div>
</div>
<a name="N1159D" class="indexterm"></a>
<p>
<span class="bold"><strong>CREATE SEQUENCE</strong></span>
</p>
<p>
<span class="emphasis"><em>sequence generator definition</em></span>
</p>
<p>
<code class="literal">&lt;sequence generator definition&gt; ::= CREATE
      SEQUENCE &lt;sequence generator name&gt; [ &lt;sequence generator
      options&gt; ]</code>
</p>
<p>
<code class="literal">&lt;sequence generator options&gt; ::= &lt;sequence
      generator option&gt; ...</code>
</p>
<p>
<code class="literal">&lt;sequence generator option&gt; ::= &lt;sequence
      generator data type option&gt; | &lt;common sequence generator
      options&gt;</code>
</p>
<p>
<code class="literal">&lt;common sequence generator options&gt; ::=
      &lt;common sequence generator option&gt; ...</code>
</p>
<p>
<code class="literal">&lt;common sequence generator option&gt; ::=
      &lt;sequence generator start with option&gt; | &lt;basic sequence
      generator option&gt;</code>
</p>
<p>
<code class="literal">&lt;basic sequence generator option&gt; ::=
      &lt;sequence generator increment by option&gt; | &lt;sequence generator
      maxvalue option&gt; | &lt;sequence generator minvalue option&gt; |
      &lt;sequence generator cycle option&gt;</code>
</p>
<p>
<code class="literal">&lt;sequence generator data type option&gt; ::= AS
      &lt;data type&gt;</code>
</p>
<p>
<code class="literal">&lt;sequence generator start with option&gt; ::= START
      WITH &lt;sequence generator start value&gt;</code>
</p>
<p>
<code class="literal">&lt;sequence generator start value&gt; ::= &lt;signed
      numeric literal&gt;</code>
</p>
<p>
<code class="literal">&lt;sequence generator increment by option&gt; ::=
      INCREMENT BY &lt;sequence generator increment&gt;</code>
</p>
<p>
<code class="literal">&lt;sequence generator increment&gt; ::= &lt;signed
      numeric literal&gt;</code>
</p>
<p>
<code class="literal">&lt;sequence generator maxvalue option&gt; ::=
      MAXVALUE &lt;sequence generator max value&gt; | NO
      MAXVALUE</code>
</p>
<p>
<code class="literal">&lt;sequence generator max value&gt; ::= &lt;signed
      numeric literal&gt;</code>
</p>
<p>
<code class="literal">&lt;sequence generator minvalue option&gt; ::=
      MINVALUE &lt;sequence generator min value&gt; | NO
      MINVALUE</code>
</p>
<p>
<code class="literal">&lt;sequence generator min value&gt; ::= &lt;signed
      numeric literal&gt;</code>
</p>
<p>
<code class="literal">&lt;sequence generator cycle option&gt; ::= CYCLE | NO
      CYCLE</code>
</p>
<p>Define a named sequence generator. A SEQUENCE object generates a
      sequence of integers according to the specified rules. The simple
      definition without the options defines a sequence of numbers in INTEGER
      type starting at 1 and incrementing by 1. By default the
      <code class="literal">CYCLE</code> property is set and the minimum and maximum
      limits are the minimum and maximum limits of the type of returned
      values. There are self-explanatory options for changing various
      properties of the sequence. The <code class="literal">MAXVALUE</code> and
      <code class="literal">MINVALUE</code> specify the upper and lower limits. If
      <code class="literal">CYCLE</code> is specified, after the sequence returns the
      highest or lowest value in range, the next value will respectively be
      the lowest or highest value in range. If <code class="literal">NO CYCLE</code> is
      specified, the use of the sequence generator results in an error once
      the limit has been reached.</p>
<p>The integer types: SMALLINT, INTEGER, BIGINT, DECIMAL and NUMERIC
      can be used as the type of the sequence. DECIMAL and NUMERIC types must
      have a scale of 0 and a precision not exceeding 18.</p>
<a name="N115EC" class="indexterm"></a>
<p>
<span class="bold"><strong>ALTER SEQUENCE</strong></span>
</p>
<p>
<span class="emphasis"><em>alter sequence generator
      statement</em></span>
</p>
<p>
<code class="literal">&lt;alter sequence generator statement&gt; ::= ALTER
      SEQUENCE &lt;sequence generator name&gt; &lt;alter sequence generator
      options&gt;</code>
</p>
<p>
<code class="literal">&lt;alter sequence generator options&gt; ::= &lt;alter
      sequence generator option&gt;...</code>
</p>
<p>
<code class="literal">&lt;alter sequence generator option&gt; ::= &lt;alter
      sequence generator restart option&gt; | &lt;basic sequence generator
      option&gt;</code>
</p>
<p>
<code class="literal">&lt;alter sequence generator restart option&gt; ::=
      RESTART [ WITH &lt;sequence generator restart value&gt;
      ]</code>
</p>
<p>
<code class="literal">&lt;sequence generator restart value&gt; ::=
      &lt;signed numeric literal&gt;</code>
</p>
<p>Change the definition of a named sequence generator. The same
      options that are used in the definition of the SEQUENCE can be used to
      alter it. The exception is the option for the start value which is
      <code class="literal">RESTART WITH</code> for the ALTER SEQUENCE statement.</p>
<p>If RESTART is used by itself (without a value), then the current
      value of the sequence is reset to the start value. Otherwise, the
      current value is reset to the given restart value.</p>
<a name="N1160E" class="indexterm"></a>
<p>
<span class="bold"><strong>DROP SEQUENCE</strong></span>
</p>
<p>
<span class="emphasis"><em>drop sequence generator
      statement</em></span>
</p>
<p>
<code class="literal">&lt;drop sequence generator statement&gt; ::= DROP
      SEQUENCE [ IF EXISTS ] &lt;sequence generator name&gt; [ IF EXISTS ]
      &lt;drop behavior&gt;</code>
</p>
<p>Destroy an external sequence generator. If the <code class="literal">&lt;drop
      behavior&gt;</code> is <code class="literal">CASCADE</code>, then all objects
      that reference the sequence are dropped. These objects can be VIEW,
      ROUTINE or TRIGGER objects.</p>
</div>
<div class="section" title="SQL Procedure Statement">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dbc_procedure_satement"></a>SQL Procedure Statement</h3>
</div>
</div>
</div>
<a name="N1162A" class="indexterm"></a>
<p>
<span class="bold"><strong>SQL procedure
      statement</strong></span>
</p>
<p>
<span class="emphasis"><em>SQL procedure statement</em></span>
</p>
<p>The definition of CREATE TRIGGER and CREATE PROCEDURE
      statements refers to &lt;SQL procedure statement&gt;. The definition of
      this element is given below. However, only a subset of these statements
      are allowed in trigger or routine definition.</p>
<p>
<code class="literal">&lt;SQL procedure statement&gt; ::= &lt;SQL executable
      statement&gt;</code>
</p>
<p>
<code class="literal">&lt;SQL executable statement&gt; ::= &lt;SQL schema
      statement&gt; | &lt;SQL data statement&gt; | &lt;SQL control
      statement&gt; | &lt;SQL transaction statement&gt; | &lt;SQL connection
      statement&gt; | &lt;SQL session statement&gt; | &lt;SQL diagnostics
      statement&gt; | &lt;SQL dynamic statement&gt;</code>
</p>
<p>
<code class="literal">&lt;SQL schema statement&gt; ::= &lt;SQL schema
      definition statement&gt; | &lt;SQL schema manipulation
      statement&gt;</code>
</p>
<p>
<code class="literal">&lt;SQL schema definition statement&gt; ::= &lt;schema
      definition&gt; | &lt;table definition&gt; | &lt;view definition&gt; |
      &lt;SQL-invoked routine&gt; | &lt;grant statement&gt; | &lt;role
      definition&gt; | &lt;domain definition&gt; | &lt;character set
      definition&gt; | &lt;collation definition&gt; | &lt;transliteration
      definition&gt; | &lt;assertion definition&gt; | &lt;trigger
      definition&gt; | &lt;user-defined type definition&gt; | &lt;user-defined
      cast definition&gt; | &lt;user-defined ordering definition&gt; |
      &lt;transform definition&gt; | &lt;sequence generator
      definition&gt;</code>
</p>
<p>
<code class="literal">&lt;SQL schema manipulation statement&gt; ::= &lt;drop
      schema statement&gt; | &lt;alter table statement&gt; | &lt;drop table
      statement&gt; | &lt;drop view statement&gt; | &lt;alter routine
      statement&gt; | &lt;drop routine statement&gt; | &lt;drop user-defined
      cast statement&gt; | &lt;revoke statement&gt; | &lt;drop role
      statement&gt; | &lt;alter domain statement&gt; | &lt;drop domain
      statement&gt; | &lt;drop character set statement&gt; | &lt;drop
      collation statement&gt; | &lt;drop transliteration statement&gt; |
      &lt;drop assertion statement&gt; | &lt;drop trigger statement&gt; |
      &lt;alter type statement&gt; | &lt;drop data type statement&gt; |
      &lt;alter sequence generator statement&gt; | &lt;drop sequence generator
      statement&gt;</code>
</p>
</div>
<div class="section" title="Other Schema Object Creation">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dbc_other_object_creation"></a>Other Schema Object Creation</h3>
</div>
</div>
</div>
<a name="N1164B" class="indexterm"></a>
<p>
<span class="bold"><strong>CREATE INDEX</strong></span>
</p>
<p>
<span class="emphasis"><em>create index statement</em></span>
</p>
<p>
<code class="literal">&lt;create index statement&gt; ::= CREATE INDEX
      &lt;index name&gt; ON &lt;table name&gt; &lt;left paren&gt; {&lt;column
      name&gt; [ASC | DESC]}, ... &lt;right paren&gt;</code>
</p>
<p>Creates an index on a group of columns of a table. The optional
      [ASC | DESC] specifies if the column is indexed in the ascending or
      descending order, but has no effect on how the index is created (it is
      allowed for compatibility with other database engines). HyperSQL can use
      all indexes in ascending or descending order as needed. Indexes should
      not duplicate the columns of PRIMARY KEY, UNIQUE or FOREIGN key
      constraints as each of these constraints creates an index
      automatically.</p>
<a name="N1165C" class="indexterm"></a>
<p>
<span class="bold"><strong>DROP INDEX</strong></span>
</p>
<p>
<span class="emphasis"><em>drop index statement</em></span>
</p>
<p>
<code class="literal">&lt;drop index statement&gt; ::= DROP INDEX [ IF
      EXISTS ] &lt;index name&gt; [ IF EXISTS ]</code>
</p>
<p>Destroy an index.</p>
<a name="N1166D" class="indexterm"></a>
<p>
<span class="bold"><strong>ALTER INDEX</strong></span>
</p>
<p>
<span class="emphasis"><em>change the columns of an index</em></span>
</p>
<p>
<code class="literal">&lt;alter index statement&gt; ::= ALTER INDEX
      &lt;index name&gt; &lt;left paren&gt; {&lt;column name&gt;} , ...
      &lt;right paren&gt;</code>
</p>
<p>Redefine an index with a new column list. This statement is
      more efficient than dropping an existing index and creating a new
      one.</p>
<a name="N1167E" class="indexterm"></a>
<p>
<span class="bold"><strong>CREATE TYPE</strong></span>
</p>
<p>
<span class="emphasis"><em>user-defined type definition</em></span>
</p>
<p>
<code class="literal">&lt;user-defined type definition&gt; ::= CREATE TYPE
      &lt;user-defined type body&gt;</code>
</p>
<p>
<code class="literal">&lt;user-defined type body&gt; ::= &lt;schema-resolved
      user-defined type name&gt; [ AS &lt;representation&gt;
      ]</code>
</p>
<p>
<code class="literal">&lt;representation&gt; ::= &lt;predefined
      type&gt;</code>
</p>
<p>Define a user-defined type. Currently only simple distinct
      types can be defined without further attributes.</p>
<a name="N11695" class="indexterm"></a>
<p>
<span class="bold"><strong>CREATE CAST</strong></span>
</p>
<p>
<span class="emphasis"><em>user-defined cast definition</em></span>
</p>
<p>
<code class="literal">&lt;user-defined cast definition&gt; ::= CREATE CAST
      &lt;left paren&gt; &lt;source data type&gt; AS &lt;target data type&gt;
      &lt;right paren&gt; WITH &lt;cast function&gt; [ AS ASSIGNMENT
      ]</code>
</p>
<p>
<code class="literal">&lt;cast function&gt; ::= &lt;specific routine
      designator&gt;</code>
</p>
<p>
<code class="literal">&lt;source data type&gt; ::= &lt;data
      type&gt;</code>
</p>
<p>
<code class="literal">&lt;target data type&gt; ::= &lt;data
      type&gt;</code>
</p>
<p>Define a user-defined cast. This feature may be supported in a
      future versions of HyperSQL.</p>
<a name="N116AF" class="indexterm"></a>
<p>
<span class="bold"><strong>DROP CAST</strong></span>
</p>
<p>
<span class="emphasis"><em>drop user-defined cast statement</em></span>
</p>
<p>
<code class="literal">&lt;drop user-defined cast statement&gt; ::= DROP CAST
      &lt;left paren&gt; &lt;source data type&gt; AS &lt;target data type&gt;
      &lt;right paren&gt; &lt;drop behavior&gt;</code>
</p>
<p>Destroy a user-defined cast. This feature may be supported in a
      future versions of HyperSQL.</p>
<a name="N116C0" class="indexterm"></a>
<p>
<span class="bold"><strong>CREATE CHARACTER SET</strong></span>
</p>
<p>
<span class="emphasis"><em>character set definition</em></span>
</p>
<p>
<code class="literal">&lt;character set definition&gt; ::= CREATE CHARACTER
      SET &lt;character set name&gt; [ AS ] &lt;character set source&gt; [
      &lt;collate clause&gt; ]</code>
</p>
<p>
<code class="literal">&lt;character set source&gt; ::= GET &lt;character set
      specification&gt;</code>
</p>
<p>Define a character set. A new CHARACTER SET is based on an
      existing CHARACTER SET. The optional <code class="literal">&lt;collate
      clause&gt;</code> specifies the collation to be used, otherwise the
      collation is inherited from the default collation for the source
      CHARACTER SET. Currently this statement has no effect, as the character
      set used by HSQLDB is Unicode and there is no need for subset character
      sets.</p>
<a name="N116D7" class="indexterm"></a>
<p>
<span class="bold"><strong>DROP CHARACTER SET</strong></span>
</p>
<p>
<span class="emphasis"><em>drop character set statement</em></span>
</p>
<p>
<code class="literal">&lt;drop character set statement&gt; ::= DROP
      CHARACTER SET &lt;character set name&gt;</code>
</p>
<p>Destroy a character set. If the character set name is
      referenced in any database object, the command fails. Note that
      <code class="literal">CASCADE</code> or <code class="literal">RESTRICT</code> cannot be
      specified for this command.</p>
<a name="N116EE" class="indexterm"></a>
<p>
<span class="bold"><strong>CREATE COLLATION</strong></span>
</p>
<p>
<span class="emphasis"><em>collation definition</em></span>
</p>
<p>
<code class="literal">&lt;collation definition&gt; ::= CREATE COLLATION
      &lt;collation name&gt; FOR &lt;character set specification&gt; FROM
      &lt;existing collation name&gt; [ &lt;pad characteristic&gt;
      ]</code>
</p>
<p>
<code class="literal">&lt;existing collation name&gt; ::= &lt;collation
      name&gt;</code>
</p>
<p>
<code class="literal">&lt;pad characteristic&gt; ::= NO PAD | PAD
      SPACE</code>
</p>
<p>Define a collation. A new collation is based on an existing
      COLLATION and applies to an existing CHARACTER SET. The &lt;character
      set specification&gt; is always SQL_TEXT. The &lt;existing collation
      name&gt; is either SQL_TEXT or one of the language collations supported
      by HSQLDB. The <code class="literal">&lt;pad characteristic&gt;</code> specifies
      whether strings are padded with spaces for comparison.</p>
<p>This statement is typically used when a collation is required that
      does not pad spaces before comparing two strings. For example,
      <code class="literal">CREATE COLLATION FRENCH_NOPAD FOR INFORMATION_SCHEMA.SQL_TEXT
      FROM "French" NO PAD</code>, results in a French collation without
      padding. This collation can be used for sorting or for individual
      columns of tables.</p>
<a name="N1170D" class="indexterm"></a>
<p>
<span class="bold"><strong>DROP COLLATION</strong></span>
</p>
<p>
<span class="emphasis"><em>drop collation statement</em></span>
</p>
<p>
<code class="literal">&lt;drop collation statement&gt; ::= DROP COLLATION
      &lt;collation name&gt; &lt;drop behavior&gt;</code>
</p>
<p>Destroy a collation. If the <code class="literal">&lt;drop
      behavior&gt;</code> is <code class="literal">CASCADE</code>, then all
      references to the collation revert to the default collation that would
      be in force if the dropped collation was not specified.</p>
<a name="N11724" class="indexterm"></a>
<p>
<span class="bold"><strong>CREATE TRANSLATION</strong></span>
</p>
<p>
<span class="emphasis"><em>transliteration definition</em></span>
</p>
<p>
<code class="literal">&lt;transliteration definition&gt; ::= CREATE
      TRANSLATION &lt;transliteration name&gt; FOR &lt;source character set
      specification&gt; TO &lt;target character set specification&gt; FROM
      &lt;transliteration source&gt;</code>
</p>
<p>
<code class="literal">&lt;source character set specification&gt; ::=
      &lt;character set specification&gt;</code>
</p>
<p>
<code class="literal">&lt;target character set specification&gt; ::=
      &lt;character set specification&gt;</code>
</p>
<p>
<code class="literal">&lt;transliteration source&gt; ::= &lt;existing
      transliteration name&gt; | &lt;transliteration
      routine&gt;</code>
</p>
<p>
<code class="literal">&lt;existing transliteration name&gt; ::=
      &lt;transliteration name&gt; </code>
</p>
<p>
<code class="literal">&lt;transliteration routine&gt; ::= &lt;specific
      routine designator&gt;</code>
</p>
<p>Define a character transliteration. This feature may be supported
      in a future versions of HyperSQL.</p>
<a name="N11744" class="indexterm"></a>
<p>
<span class="bold"><strong>DROP TRANSLATION</strong></span>
</p>
<p>
<span class="emphasis"><em>drop transliteration statement</em></span>
</p>
<p>
<code class="literal">&lt;drop transliteration statement&gt; ::= DROP
      TRANSLATION &lt;transliteration name&gt;</code>
</p>
<p>Destroy a character transliteration. This feature may be
      supported in a future versions of HyperSQL.</p>
<a name="N11755" class="indexterm"></a>
<p>
<span class="bold"><strong>CREATE ASSERTION</strong></span>
</p>
<p>
<span class="emphasis"><em>assertion definition</em></span>
</p>
<p>
<code class="literal">&lt;assertion definition&gt; ::= CREATE ASSERTION
      &lt;constraint name&gt; CHECK &lt;left paren&gt; &lt;search
      condition&gt; &lt;right paren&gt; [ &lt;constraint characteristics&gt;
      ]</code>
</p>
<p>Specify an integrity constraint. This feature may be supported
      in a future versions of HyperSQL.</p>
<a name="N11766" class="indexterm"></a>
<p>
<span class="bold"><strong>DROP ASSERTION</strong></span>
</p>
<p>
<span class="emphasis"><em>drop assertion statement</em></span>
</p>
<p>
<code class="literal">&lt;drop assertion statement&gt; ::= DROP ASSERTION
      &lt;constraint name&gt; [ &lt;drop behavior&gt; ]</code>
</p>
<p>Destroy an assertion. This feature may be supported in a future
      versions of HyperSQL.</p>
</div>
</div>
<div class="section" title="The Information Schema">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="dbc_information_schema"></a>The Information Schema</h2>
</div>
</div>
</div>
<p>The Information Schema is a special schema in each catalog. The SQL
    Standard defines a number of character sets and domains in this schema. In
    addition, all the implementation-defined collations belong to the
    Information Schema.</p>
<p>The SQL Standard defines many views in the Information Schema. These
    views show the properties of the database objects that currently exist in
    the database. When a user accesses one these views, only the properties of
    database objects that the user can access are included.</p>
<p>HyperSQL supports all the views defined by the Standard, apart from
    a few views that report on extended user-defined types and other optional
    features of the Standard that are not supported by HyperSQL.</p>
<p>HyperSQL also adds some views to the Information Schema. These views
    are for features that are not reported in any of the views defined by the
    Standard, or for use by JDBC DatabaseMetaData.</p>
<div class="section" title="Predefined Character Sets, Collations and Domains">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dbc_char_sets_info_schema"></a>Predefined Character Sets, Collations and Domains</h3>
</div>
</div>
</div>
<p>The SQL Standard defines a number of character sets and domains in
      the INFORMATION SCHEMA.</p>
<p>These domains are used in the INFORMATION SCHEMA views:</p>
<p>CARDINAL_NUMBER, YES_OR_NO, CHARACTER_DATA, SQL_IDENTIFIER,
      TIME_STAMP</p>
<p>All available collations are in the INFORMATION
      SCHEMA.</p>
</div>
<div class="section" title="Views in INFORMATION SCHEMA">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dbc_views_info_schema"></a>Views in INFORMATION SCHEMA</h3>
</div>
</div>
</div>
<p>HyperSQL supports a vast range of views in the INFORMATION_SCHEMA.
      These include views specified by the SQL Standard, SQL/Schemata part,
      plus views that are specific to HyperSQL and are used for JDBC
      DatabaseMetaData queries, which are based on SQL/CLI part, or other
      information that is not covered by the SQL Standard. The names of views
      that are not part of SQL/Schemata start with SYSTEM_.</p>
<p>The views cover different types of information. These are covered
      in the next sections.</p>
</div>
<div class="section" title="Visibility of Information">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dbc_visibility_info_schema"></a>Visibility of Information</h3>
</div>
</div>
</div>
<p>Users with the special ADMIN role can see the full information on
      all database objects. Ordinary, non-admin users can see information on
      the objects for which they have some privileges.</p>
<p>The rows returned to a non-admin user exclude objects on which the
      user has no privilege. The extent of the information in visible rows
      varies with the user's privilege. For example, the owner of a VIEW can
      see the text of the view query, but a user of the view cannot see this
      text. When a user cannot see the contents of some column, null is
      returned for that column.</p>
</div>
<div class="section" title="Name Information">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dbc_name_info_schema"></a>Name Information</h3>
</div>
</div>
</div>
<p>The names of database objects are stored in hierarchical views.
      The top level view is INFORMATION_SCHEMA_CATALOG_NAME.</p>
<p>Below this level, there is a group of views that covers
      authorizations and roles, without referencing schema objects. These are
      AUTHORIZATIONS and ADMINSTRABLE_ROLE_AUTHORIZATIONS.</p>
<p>Also below the top level, there is the SCHEMATA view, which lists
      the schemas in the catalog.</p>
<p>The views that refer to top-level schema objects are divided by
      object type. These includes ASSERTIONS, CHARACTER_SETS, COLLATIONS,
      DOMAINS, ROUTINES, SEQUENCES, TABLES, USER_DEFINED_TYPES and
      VIEWS.</p>
<p>There are views that refer to objects that are dependent on the
      top-level schema objects. These include COLUMNS and PARAMETERS, views
      for constraints, including CHECK_CONSTRAINTS, REFERENTIAL_CONSTRAINTS
      and TABLE_CONSTRAINTS, and finally the TRIGGERS view.</p>
<p>The usage of each type of top-level object by another is covered
      by several views. For example TRIGGER_SEQUENCE_USAGE or
      ROUTINE_TABLE_USAGE.</p>
<p>Several other views list the individual privileges owned or
      granted to each AUTHORIZATION. For example ROLE_ROUTINE_GRANTS or
      TABLE_PRIVILEGES.</p>
</div>
<div class="section" title="Data Type Information">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dbc_data_type_info_schema"></a>Data Type Information</h3>
</div>
</div>
</div>
<p>The INFORMATION_SCHEMA contains comprehensive information on the
      data types of each schema object and its elements. For example, the
      ROUTINES view includes the return data type for each FUNCTION
      definition. The columns for this information contain nulls for rows that
      cover PROCEDURE definitions.</p>
<p>The COLUMNS, PARAMETERS and SEQUENCES views contain the type
      information in columns with similar names.</p>
<p>The type information for ARRAY types is returned in the
      ELEMENT_TYPES view. When a row of the COLUMNS or other view indicates
      that the type of the object is an ARRAY type, then there is a
      corresponding entry for this row in the ELEMENT_TYPES view. The
      following columns in the ELEMENTS_TYPES view identify the database
      object whose data type is being described: OBJECT_CATALOG,
      OBJECT_SCHEMA, OBJECT_NAME, OBJECT_TYPE, COLLECTION_TYPE_IDENTIFIER. The
      last column's counterpart in the COLUMNS view is named differently as
      DTD_IDENTIFIER. So in order to determine the array element type of a
      column, an equi-join between the COLUMNS and ELEMENT_TYPES tables on the
      six listed columns in the ELEMENT_TYPES view and their counterparts in
      the COLUMNS view is needed.</p>
</div>
<div class="section" title="Product Information">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dbc_product_info_schema"></a>Product Information</h3>
</div>
</div>
</div>
<p>A group of views, including SQL_IMPLEMENTATION_INFO, SQL_FEATURES,
      SQL_SIZING and others cover the capabilities of HyperSQL in detail.
      These views hold static data and can be explored even when the database
      is empty.</p>
</div>
<div class="section" title="Operations Information">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dbc_operations_info_schema"></a>Operations Information</h3>
</div>
</div>
</div>
<p>There are some HyperSQL custom views cover the current state of
      operation of the database. These include SYSTEM_CACHEINFO,
      SYSTEM_SESSIONINFO and SYSTEM_SESSIONS views.</p>
</div>
<div class="section" title="SQL Standard Views">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dbc_standard_views_info_schema"></a>SQL Standard Views</h3>
</div>
</div>
</div>
<p>The following views are defined by the SQL Standard and supported
      by HyperSQL. The columns and contents exactly match the Standard
      requirements.</p>
<a name="N117CD" class="indexterm"></a>
<p>ADMINISTRABLE_ROLE_AUTHORIZATIONS</p>
<p>Information on ROLE authorizations, all granted by the admin
      role.</p>
<a name="N117D6" class="indexterm"></a>
<p>APPLICABLE_ROLES</p>
<p>Information on ROLE authorizations for the current user</p>
<a name="N117DF" class="indexterm"></a>
<p>ASSERTIONS</p>
<p>Empty view as ASSERTION objects are not yet supported.</p>
<a name="N117E8" class="indexterm"></a>
<p>AUTHORIZATIONS</p>
<p>Top level information on USER and ROLE objects in the
      database</p>
<a name="N117F1" class="indexterm"></a>
<p>CHARACTER_SETS</p>
<p>List of supported CHARACTER SET objects</p>
<a name="N117FA" class="indexterm"></a>
<p>CHECK_CONSTRAINTS</p>
<p>Additional information specific to each CHECK constraint,
      including the search condition</p>
<a name="N11803" class="indexterm"></a>
<p>CHECK_CONSTRAINT_ROUTINE_USAGE</p>
<p>Information on FUNCTION objects referenced in CHECK constraints
      search conditions</p>
<a name="N1180C" class="indexterm"></a>
<p>COLLATIONS</p>
<p>Information on collations supported by the database.</p>
<a name="N11815" class="indexterm"></a>
<p>COLUMNS</p>
<p>Information on COLUMN objects in TABLE and VIEW definitions</p>
<a name="N1181E" class="indexterm"></a>
<p>COLUMN_COLUMN_USAGE</p>
<p>Information on references to COLUMN objects from other, GENERATED,
      COLUMN objects</p>
<a name="N11827" class="indexterm"></a>
<p>COLUMN_DOMAIN_USAGE</p>
<p>Information on DOMAIN objects used in type definition of COLUMN
      objects</p>
<a name="N11830" class="indexterm"></a>
<p>COLUMN_PRIVILEGES</p>
<p>Information on privileges on each COLUMN object, granted to
      different ROLE and USER authorizations</p>
<a name="N11839" class="indexterm"></a>
<p>COLUMN_UDT_USAGE</p>
<p>Information on distinct TYPE objects used in type definition of
      COLUMN objects</p>
<a name="N11842" class="indexterm"></a>
<p>CONSTRAINT_COLUMN_USAGE</p>
<p>Information on COLUMN objects referenced by CONSTRAINT objects in
      the database</p>
<a name="N1184B" class="indexterm"></a>
<p>CONSTRAINT_TABLE_USAGE</p>
<p>Information on TABLE and VIEW objects referenced by CONSTRAINT
      objects in the database</p>
<a name="N11854" class="indexterm"></a>
<p>DATA_TYPE_PRIVILEGES</p>
<p>Information on top level schema objects of various kinds that
      reference TYPE objects</p>
<a name="N1185D" class="indexterm"></a>
<p>DOMAINS</p>
<p>Top level information on DOMAIN objects in the database.</p>
<a name="N11866" class="indexterm"></a>
<p>DOMAIN_CONSTRAINTS</p>
<p>Information on CONSTRAINT definitions used for DOMAIN
      objects</p>
<a name="N1186F" class="indexterm"></a>
<p>ELEMENT_TYPES</p>
<p>Information on the type of elements of ARRAY used in database
      columns or routine parameters and return values</p>
<a name="N11878" class="indexterm"></a>
<p>ENABLED_ROLES</p>
<p>Information on ROLE privileges enabled for the current
      session</p>
<a name="N11881" class="indexterm"></a>
<p>INFORMATION_SCHEMA_CATALOG_NAME</p>
<p>Information on the single CATALOG object of the database</p>
<a name="N1188A" class="indexterm"></a>
<p>KEY_COLUMN_USAGE</p>
<p>Information on COLUMN objects of tables that are used by PRIMARY
      KEY, UNIQUE and FOREIGN KEY constraints</p>
<a name="N11893" class="indexterm"></a>
<p>PARAMETERS</p>
<p>Information on parameters of each FUNCTION or PROCEDURE</p>
<a name="N1189C" class="indexterm"></a>
<p>REFERENTIAL_CONSTRAINTS</p>
<p>Additional information on FOREIGN KEY constraints, including
      triggered action and name of UNIQUE constraint they refer to</p>
<a name="N118A5" class="indexterm"></a>
<p>ROLE_AUTHORIZATION_DESCRIPTORS</p>
<a name="N118AC" class="indexterm"></a>
<p>ROLE_COLUMN_GRANTS</p>
<p>Information on privileges on COLUMN objects granted to or by the
      current session roles</p>
<a name="N118B5" class="indexterm"></a>
<p>ROLE_ROUTINE_GRANTS</p>
<p>Information on privileges on FUNCTION and PROCEDURE objects
      granted to or by the current session roles</p>
<a name="N118BE" class="indexterm"></a>
<p>ROLE_TABLE_GRANTS</p>
<p>Information on privileges on TABLE and VIEW objects granted to or
      by the current session roles</p>
<a name="N118C7" class="indexterm"></a>
<p>ROLE_UDT_GRANTS</p>
<p>Information on privileges on TYPE objects granted to or by the
      current session roles</p>
<a name="N118D0" class="indexterm"></a>
<p>ROLE_USAGE_GRANTS</p>
<p>Information on privileges on USAGE privileges granted to or by the
      current session roles</p>
<a name="N118D9" class="indexterm"></a>
<p>ROUTINE_COLUMN_USAGE</p>
<p>Information on COLUMN objects of different tables that are
      referenced in FUNCTION and PROCEDURE definitions</p>
<a name="N118E2" class="indexterm"></a>
<p>ROUTINE_JAR_USAGE</p>
<p>Information on JAR usage by Java language FUNCTION and PROCEDURE
      objects.</p>
<a name="N118EB" class="indexterm"></a>
<p>ROUTINE_PRIVILEGES</p>
<p>Information on EXECUTE privileges granted on PROCEDURE and
      FUNCTION objects</p>
<a name="N118F4" class="indexterm"></a>
<p>ROUTINE_ROUTINE_USAGE</p>
<p>Information on PROCEDURE and FUNCTION objects that are referenced
      in FUNCTION and PROCEDURE definitions</p>
<a name="N118FD" class="indexterm"></a>
<p>ROUTINE_SEQUENCE_USAGE</p>
<p>Information on SEQUENCE objects that are referenced in FUNCTION
      and PROCEDURE definitions</p>
<a name="N11906" class="indexterm"></a>
<p>ROUTINE_TABLE_USAGE</p>
<p>Information on TABLE and VIEW objects that are referenced in
      FUNCTION and PROCEDURE definitions</p>
<a name="N1190F" class="indexterm"></a>
<p>ROUTINES</p>
<p>Top level information on all PROCEDURE and FUNCTION objects in the
      database</p>
<a name="N11918" class="indexterm"></a>
<p>SCHEMATA</p>
<p>Information on all the SCHEMA objects in the database</p>
<a name="N11921" class="indexterm"></a>
<p>SEQUENCES</p>
<p>Information on SEQUENCE objects</p>
<a name="N1192A" class="indexterm"></a>
<p>SQL_FEATURES</p>
<p>List of all SQL:2008 standard features, including information on
      whether they are supported or not supported by HyperSQL</p>
<a name="N11933" class="indexterm"></a>
<p>SQL_IMPLEMENTATION_INFO</p>
<p>Information on name, capabilities and defaults of the database
      engine software.</p>
<a name="N1193C" class="indexterm"></a>
<p>SQL_PACKAGES</p>
<p>List of the SQL:2008 Standard packages, including information on
      whether they are supported or not supported by HyperSQL</p>
<a name="N11945" class="indexterm"></a>
<p>SQL_PARTS</p>
<p>List of the SQL:2008 Standard parts, including information on
      whether they are supported or not supported by HyperSQL</p>
<a name="N1194E" class="indexterm"></a>
<p>SQL_SIZING</p>
<p>List of the SQL:2008 Standard maximum supported sizes for
      different features as supported by HyperSQL</p>
<a name="N11957" class="indexterm"></a>
<p>SQL_SIZING_PROFILES</p>
<a name="N1195E" class="indexterm"></a>
<p>TABLES</p>
<p>Information on all TABLE and VIEW object, including the
      INFORMATION_SCHEMA views themselves</p>
<a name="N11967" class="indexterm"></a>
<p>TABLE_CONSTRAINTS</p>
<p>Information on all table level constraints, including PRIMARY KEY,
      UNIQUE, FOREIGN KEY and CHECK constraints</p>
<a name="N11970" class="indexterm"></a>
<p>TABLE_PRIVILEGES</p>
<p>Information on privileges on TABLE and VIEW objects owned or given
      to the current user</p>
<a name="N11979" class="indexterm"></a>
<p>TRANSLATIONS</p>
<a name="N11980" class="indexterm"></a>
<p>TRIGGERED_UPDATE_COLUMNS</p>
<p>Information on columns that have been used in TRIGGER definitions
      in the ON UPDATE clause</p>
<a name="N11989" class="indexterm"></a>
<p>TRIGGERS</p>
<p>Top level information on the TRIGGER definitions in the
      databases</p>
<a name="N11992" class="indexterm"></a>
<p>TRIGGER_COLUMN_USAGE</p>
<p>Information on COLUMN objects that have been referenced in the
      body of TRIGGER definitions</p>
<a name="N1199B" class="indexterm"></a>
<p>TRIGGER_ROUTINE_USAGE</p>
<p>Information on FUNCTION and PROCEDURE objects that have been used
      in TRIGGER definitions</p>
<a name="N119A4" class="indexterm"></a>
<p>TRIGGER_SEQUENCE_USAGE</p>
<p>Information on SEQUENCE objects that been referenced in TRIGGER
      definitions</p>
<a name="N119AD" class="indexterm"></a>
<p>TRIGGER_TABLE_USAGE</p>
<p>Information on TABLE and VIEW objects that have been referenced in
      TRIGGER definitions</p>
<a name="N119B6" class="indexterm"></a>
<p>USAGE_PRIVILEGES</p>
<p>Information on USAGE privileges granted to or owned by the current
      user</p>
<a name="N119BF" class="indexterm"></a>
<p>USER_DEFINED_TYPES</p>
<p>Top level information on TYPE objects in the database</p>
<a name="N119C8" class="indexterm"></a>
<p>VIEWS</p>
<p>Top Level information on VIEW objects in the database</p>
<a name="N119D1" class="indexterm"></a>
<p>VIEW_COLUMN_USAGE</p>
<p>Information on COLUMN objects referenced in the query expressions
      of the VIEW objects</p>
<a name="N119DA" class="indexterm"></a>
<p>VIEW_ROUTINE_USAGE</p>
<p>Information on FUNCTION and PROCEDURE objects that have been used
      in the query expressions of the VIEW objects</p>
<a name="N119E3" class="indexterm"></a>
<p>VIEW_TABLE_USAGE</p>
<p>Information on TABLE and VIEW objects that have been referenced in
      the query expressions of the VIEW objects</p>
<div class="section" title="HyperSQL Custom Views">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="dbc_hypersql_views_info_schema"></a>HyperSQL Custom Views</h4>
</div>
</div>
</div>
<p>The following views are specific to HyperSQL. Most of these
        views are used directly by JDBC DatabaseMetaData method calls and are
        indicated as such. Some views contain information that is specific to
        HyperSQL and is not covered by the SQL Standard views.</p>
<a name="N119F2" class="indexterm"></a>
<p>SYSTEM_BESTROWIDENTIFIER</p>
<p>For DatabaseMetaData.getBestRowIdentifier</p>
<a name="N119FB" class="indexterm"></a>
<p>SYSTEM_CACHEINFO</p>
<p>Contains the current settings and variables of the data cache
        used for all CACHED tables, and the data cache of each TEXT
        table.</p>
<a name="N11A04" class="indexterm"></a>
<p>SYSTEM_COLUMN_SEQUENCE_USAGE</p>
<p>Contains a row for each column that is defined as GENERATED BY
        DEFAULT AS SEQUENCE with the column name and sequence name</p>
<a name="N11A0D" class="indexterm"></a>
<p>SYSTEM_COLUMNS</p>
<p>For DatabaseMetaData.getColumns, contains a row for each
        column</p>
<a name="N11A16" class="indexterm"></a>
<p>SYSTEM_COMMENTS</p>
<p>Contains the user-defined comments added to tables and their
        columns.</p>
<a name="N11A1F" class="indexterm"></a>
<p>SYSTEM_CONNECTION_PROPERTIES</p>
<p>For DatabaseMetaData.getClientInfoProperties</p>
<a name="N11A28" class="indexterm"></a>
<p>SYSTEM_CROSSREFERENCE</p>
<p>Full list of all columns referenced by FOREIGN KEY constraints.
        For DatabaseMetaData.getCrossReference, getExportedKeys and
        getImportedKeys.</p>
<a name="N11A31" class="indexterm"></a>
<p>SYSTEM_INDEXINFO</p>
<p>For DatabaseMetaData.getIndexInfo</p>
<a name="N11A3A" class="indexterm"></a>
<p>SYSTEM_PRIMARYKEYS</p>
<p>For DatabaseMetaData.getPrimaryKeys</p>
<a name="N11A43" class="indexterm"></a>
<p>SYSTEM_PROCEDURECOLUMNS</p>
<p>For DatabaseMetaData.getProcedureColumns</p>
<a name="N11A4C" class="indexterm"></a>
<p>SYSTEM_PROCEDURES</p>
<p>For DatabaseMetaData.getFunctionColumns, getFunctions and
        getProcedures</p>
<a name="N11A55" class="indexterm"></a>
<p>SYSTEM_PROPERTIES</p>
<p>Contains the current values of all the database level
        properties. Settings such as SQL rule enforcement, database
        transaction model and default transaction level are all reported in
        this view. The names of the properties are listed in the <a class="link" href="#dbproperties-chapt" title="Chapter&nbsp;12.&nbsp;Properties">Properties</a> chapter together with the
        corresponding SQL statements used to change the properties.</p>
<a name="N11A63" class="indexterm"></a>
<p>SYSTEM_SCHEMAS</p>
<p>For DatabaseMetaData.getSchemas</p>
<a name="N11A6C" class="indexterm"></a>
<p>SYSTEM_SEQUENCES</p>
<a name="N11A73" class="indexterm"></a>
<p>SYSTEM_SESSIONINFO</p>
<p>Information on the settings and properties of the current
        session.</p>
<a name="N11A7C" class="indexterm"></a>
<p>SYSTEM_SESSIONS</p>
<p>Information on all open sessions in the database (when used by a
        DBA user), or just the current session. Includes the current
        transaction state of each session.</p>
<a name="N11A85" class="indexterm"></a>
<p>SYSTEM_TABLES</p>
<p>Information on tables and views for
        DatabaseMetaData.getTables</p>
<a name="N11A8E" class="indexterm"></a>
<p>SYSTEM_TABLESTATS</p>
<p>Information on table spaces and cardinality for each
        table</p>
<a name="N11A97" class="indexterm"></a>
<p>SYSTEM_TABLETYPES</p>
<p>For DatabaseMetaData.getTableTypes</p>
<a name="N11AA0" class="indexterm"></a>
<p>SYSTEM_TEXTTABLES</p>
<p>Information on the settings of each text table.</p>
<a name="N11AA9" class="indexterm"></a>
<p>SYSTEM_TYPEINFO</p>
<p>For DatabaseMetaData.getTypeInfo</p>
<a name="N11AB2" class="indexterm"></a>
<p>SYSTEM_UDTS</p>
<p>For DatabaseMetaData.getUDTs</p>
<a name="N11ABB" class="indexterm"></a>
<p>SYSTEM_USERS</p>
<p>Contains the list of all users in the database (when used by a
        DBA user), or just the current user.</p>
<a name="N11AC4" class="indexterm"></a>
<p>SYSTEM_VERSIONCOLUMNS</p>
<p>For DatabaseMetaData.getVersionColumns</p>
</div>
</div>
</div>
</div>
<div class="chapter" title="Chapter&nbsp;5.&nbsp;Text Tables">
<div class="titlepage">
<div>
<div>
<h2 class="title">
<a name="texttables-chapt"></a>Chapter&nbsp;5.&nbsp;Text Tables</h2>
</div>
<div>
<h3 class="subtitle">
<i>Text Tables as a Standard Feature of Hsqldb</i>
</h3>
</div>
<div>
<div class="authorgroup">
<div class="author">
<h3 class="author">
<span class="firstname">Bob</span> <span class="surname">Preston</span>
</h3>
<div class="affiliation">
<span class="orgname">The HSQL Development Group<br>
</span>
</div>
</div>
<div class="author">
<h3 class="author">
<span class="firstname">Fred</span> <span class="surname">Toussi</span>
</h3>
<div class="affiliation">
<span class="orgname">The HSQL Development Group<br>
</span>
</div>
</div>
</div>
</div>
<div>
<p class="releaseinfo">$Revision: 5212 $</p>
</div>
<div>
<div class="legalnotice" title="Legal Notice">
<a name="N11B02"></a>
<p>Copyright 2002-2012 Bob Preston and Fred Toussi. Permission is
      granted to distribute this document without any alteration under the
      terms of the HSQLDB license. Additional permission is granted to the
      HSQL Development Group to distribute this document with or without
      alterations under the terms of the HSQLDB license.</p>
</div>
</div>
<div>
<p class="pubdate">2014-02-13 18:21:41-0500</p>
</div>
</div>
</div>
<div class="toc">
<p>
<b>Table of Contents</b>
</p>
<dl>
<dt>
<span class="section"><a href="#ttc_overview">Overview</a></span>
</dt>
<dt>
<span class="section"><a href="#ttc_implementation">The Implementation</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#ttc_table_definition">Definition of Tables</a></span>
</dt>
<dt>
<span class="section"><a href="#ttc_scope">Scope and Reassignment</a></span>
</dt>
<dt>
<span class="section"><a href="#ttc_nulls">Null Values in Columns of Text Tables</a></span>
</dt>
<dt>
<span class="section"><a href="#ttc_configuration">Configuration</a></span>
</dt>
<dt>
<span class="section"><a href="#ttc_disconnect">Disconnecting Text Tables</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#ttc_issues">Text File Usage</a></span>
</dt>
<dt>
<span class="section"><a href="#ttc_global_props">Text File Global Properties</a></span>
</dt>
<dt>
<span class="section"><a href="#ttc_transactions">Transactions</a></span>
</dt>
</dl>
</div>
<div class="section" title="Overview">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="ttc_overview"></a>Overview</h2>
</div>
</div>
</div>
<p>Text Table support for HSQLDB was originally developed by Bob
    Preston independently from the Project. Subsequently Bob joined the
    Project and incorporated this feature into version 1.7.0, with a number of
    enhancements, especially the use of conventional SQL commands for
    specifying the files used for Text Tables.</p>
<p>In a nutshell, Text Tables are CSV or other delimited files treated
    as SQL tables. Any ordinary CSV or other delimited file can be used. The
    full range of SQL queries can be performed on these files, including
    SELECT, INSERT, UPDATE and DELETE. Indexes and unique constraints can be
    set up, and foreign key constraints can be used to enforce referential
    integrity between Text Tables themselves or with conventional
    tables.</p>
<p>The delimited file can be created by the engine, or an existing file
    can be used.</p>
<p>HyperSQL with Text Table support is the only comprehensive solution
    that employs the power of SQL and the universal reach of JDBC to handle
    data stored in text files.</p>
</div>
<div class="section" title="The Implementation">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="ttc_implementation"></a>The Implementation</h2>
</div>
</div>
</div>
<div class="section" title="Definition of Tables">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="ttc_table_definition"></a>Definition of Tables</h3>
</div>
</div>
</div>
<p>Text Tables are defined similarly to conventional tables with the
      added TEXT keyword.</p>
<pre class="programlisting"> CREATE TEXT TABLE &lt;tablename&gt; (&lt;column definition&gt; [&lt;constraint definition&gt;])</pre>
<p>The table is at first empty and cannot be written to. An
      additional SET command specifies the file and the separator character
      that the Text table uses. It assigns the file to the table.</p>
<pre class="programlisting"> SET TABLE &lt;tablename&gt; SOURCE &lt;quoted_filename_and_options&gt; [DESC]</pre>
</div>
<div class="section" title="Scope and Reassignment">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="ttc_scope"></a>Scope and Reassignment</h3>
</div>
</div>
</div>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>A Text table without a file assigned to it is READ ONLY and
          EMPTY.</p>
</li>
<li class="listitem">
<p>Reassigning a Text Table definition to a new file has
          implications in the following areas:</p>
<div class="orderedlist">
<ol class="orderedlist" type="1">
<li class="listitem">
<p>The user is required to be an administrator.</p>
</li>
<li class="listitem">
<p>Existing transactions are committed at this point.</p>
</li>
<li class="listitem">
<p>Constraints, including foreign keys referencing this
              table, are kept intact but not checked. It is the responsibility
              of the administrator to ensure their integrity.</p>
</li>
</ol>
</div>
<p>The new source file is scanned and indexes are built when it
          is assigned to the table. At this point any violation of NOT NULL,
          UNIQUE or PRIMARY KEY constraints are caught and the assignment is
          aborted. However, foreign key constraints are not checked at the
          time of assignment or reassignment of the source file.</p>
</li>
</ul>
</div>
</div>
<div class="section" title="Null Values in Columns of Text Tables">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="ttc_nulls"></a>Null Values in Columns of Text Tables</h3>
</div>
</div>
</div>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>Empty fields are treated as NULL. These are fields where there
          is nothing or just spaces between the separators.</p>
</li>
<li class="listitem">
<p>Quoted empty strings are treated as empty strings.</p>
</li>
</ul>
</div>
</div>
<div class="section" title="Configuration">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="ttc_configuration"></a>Configuration</h3>
</div>
</div>
</div>
<p>The default field separator is a comma (,). A different field
      separator can be specified within the SET TABLE SOURCE statement. For
      example, to change the field separator for the table mytable to a
      vertical bar, place the following in the SET TABLE SOURCE statement, for
      example:</p>
<div class="informalexample">
<pre class="programlisting"> SET TABLE mytable SOURCE "myfile;fs=|"</pre>
</div>
<p>Since HSQLDB treats CHAR and VARCHAR strings the same, the ability
      to assign a different separator to the latter is provided. When a
      different separator is assigned to a VARCHAR, it will terminate any CSV
      field of that type. For example, if the first field is CHAR, and the
      second field VARCHAR, and the separator fs has been defined as the pipe
      (|) and vs as the period (.) then the data in the CSV file for a row
      will look like:</p>
<pre class="screen"> First field data|Second field data.Third field data</pre>
<p>This facility in effect offers an extra, special separator which
      can be used in addition to the global separator. The following example
      shows how to change the default separator to the pipe (|), VARCHAR
      separator to the period (.) within a SET TABLE SOURCE statement:</p>
<div class="informalexample">
<pre class="programlisting"> SET TABLE mytable SOURCE "myfile;fs=|;vs=."</pre>
</div>
<p>HSQLDB also recognises the following special indicators for
      separators:</p>
<div class="variablelist" title="special indicators for separators">
<p class="title">
<b>special indicators for separators</b>
</p>
<table border="0">
<col valign="top" align="left">
<tbody>
<tr>
<td>
<p>
<span class="term">\semi</span>
</p>
</td><td>
<p>semicolon</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="term">\quote</span>
</p>
</td><td>
<p>single-quote</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="term">\space</span>
</p>
</td><td>
<p>space character</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="term">\apos</span>
</p>
</td><td>
<p>apostrophe</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="term">\n</span>
</p>
</td><td>
<p>newline - Used as an end anchor (like $ in regular
            expressions)</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="term">\r</span>
</p>
</td><td>
<p>carriage return</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="term">\t</span>
</p>
</td><td>
<p>tab</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="term">\\</span>
</p>
</td><td>
<p>backslash</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="term">\u####</span>
</p>
</td><td>
<p>a Unicode character specified in hexadecimal</p>
</td>
</tr>
</tbody>
</table>
</div>
<p>Furthermore, HSQLDB provides csv file support with three
      additional boolean options: <code class="varname">ignore_first</code>,
      <code class="varname">quoted</code> and <code class="varname">all_quoted</code>. The
      <code class="varname">ignore_first</code> option (default false) tells HSQLDB to
      ignore the first line in a file. This option is used when the first line
      of the file contains column headings. The <code class="varname">all_quoted</code>
      option (default false) tells the program that it should use quotes
      around all character fields when writing to the source file. The
      <code class="varname">quoted</code> option (default true) uses quotes only when
      necessary to distinguish a field that contains the separator character.
      It can be set to false to prevent the use of quoting altogether and
      treat quote characters as normal characters. These options may be
      specified within the <code class="literal">SET TABLE SOURCE</code>
      statement:</p>
<pre class="programlisting"> SET TABLE mytable SOURCE "myfile;ignore_first=true;all_quoted=true"</pre>
<p>When the default options <code class="literal">all_quoted=</code>
      <code class="literal">false</code> and <code class="literal">quoted=true</code> are in
      force, fields that are written to a line of the csv file will be quoted
      only if they contain the separator or the quote character. The quote
      character is doubled when used inside a string. When
      <code class="literal">all_quoted=false</code> and <code class="literal">quoted=false</code>
      the quote character is not doubled. With this option, it is not possible
      to insert any string containing the separator into the table, as it
      would become impossible to distinguish from a separator. While reading
      an existing data source file, the program treats each individual field
      separately. It determines that a field is quoted only if the first
      character is the quote character. It interprets the rest of the field on
      this basis.</p>
<p>The character encoding for the source file is<code class="literal"> ASCII
      </code>by default. To support UNICODE or source files prepared with
      different encodings this can be changed to <code class="literal">UTF-8</code> or
      any other encoding. The default is <code class="literal">encoding=ASCII </code>and
      the option <code class="literal">encoding=UTF-8</code> or other supported
      encodings can be used.</p>
<p>Finally, HSQLDB provides the ability to read a text file as READ
      ONLY, by placing the keyword "DESC" at the end of the SET TABLE SOURCE
      statement:</p>
<pre class="programlisting"> SET TABLE mytable SOURCE "myfile" DESC</pre>
<p>Text table source files are cached in memory. The maximum number
      of rows of data that are in memory at any time is controlled by the
      <code class="varname">cache_rows</code> property. The default value for
      <code class="varname">cache_rows</code> is 1000 and can be changed by setting the
      default database property .The <code class="varname">cache_size</code> property
      sets the maximum amount of memory used for each text table. The default
      is 100 KB. The properties can be set for individual text tables. These
      properties do not control the maximum size of each text table, which can
      be much larger. An example is given below:</p>
<pre class="programlisting"> SET TABLE mytable SOURCE "myfile;ignore_first=true;all_quoted=true;cache_rows=10000;cache_size=1000"</pre>
<p>The properties used in earlier versions, namely the
      <code class="varname">textdb.cache_scale</code> and the
      <code class="varname">textdb.cache_size_scale</code> can still be used for
      backward compatibility, but the new properties are preferred.</p>
<div class="variablelist" title="Supported Properties">
<p class="title">
<b>Supported Properties</b>
</p>
<table border="0">
<col valign="top" align="left">
<tbody>
<tr>
<td>
<p>
<span class="term">quoted = { true | false }</span>
</p>
</td><td>
<p>default is true. If false, treats double quotes as normal
            characters</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="term">all_quoted = { true | false }</span>
</p>
</td><td>
<p>default is false. If true, adds double quotes around all
            fields.</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="term">encoding = &lt;encoding name&gt;</span>
</p>
</td><td>
<p>character encoding for text and character fields, for
            example, encoding=UTF-8. UTF-16 cannot be used.</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="term">ignore_first = { true | false }</span>
</p>
</td><td>
<p>default is false. If true ignores the first line of the
            file</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="term">cache_rows= &lt;numeric value&gt;</span>
</p>
</td><td>
<p>rows of the text file in the cache. Default is 1000
            rows</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="term">cache_size = &lt;numeric value&gt;r</span>
</p>
</td><td>
<p>total size of the rows in the cache. Default is 100
            KB.</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="term">cache_scale= &lt;numeric value&gt; and cache_size_scale =
          &lt;numeric value&gt;</span>
</p>
</td><td>
<p>deprecated properties, replaced by cached_rows and
            cache_size properties above.</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="term">fs = &lt;unquoted character&gt;</span>
</p>
</td><td>
<p>field separator</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="term">vs = &lt;unquoted character&gt;</span>
</p>
</td><td>
<p>varchar separator</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" title="Disconnecting Text Tables">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="ttc_disconnect"></a>Disconnecting Text Tables</h3>
</div>
</div>
</div>
<p>Text tables may be <em class="glossterm">disconnected</em> from their
      underlying data source, i.e. the text file.</p>
<p>You can explicitly disconnect a text table from its file by
      issuing the following statement: </p>
<pre class="programlisting"> SET TABLE mytable SOURCE OFF</pre>
<p>Subsequently, <code class="literal">mytable</code> will be empty and
      read-only. However, the data source description will be preserved, and
      the table can be re-connected to it with </p>
<pre class="programlisting"> SET TABLE mytable SOURCE ON</pre>
<p>When a database is opened, if the source file for an existing text
      table is missing, the table remains disconnected from its data source
      but the source description is preserved. This allows the missing source
      file to be added to the directory and the table re-connected to it with
      the above command.</p>
<p>Disconnecting text tables from their source has several uses.
      While disconnected, the text source can be edited outside HSQLDB,
      provided data integrity is respected. When large text sources are used,
      and several constraints or indexes need to be created on the table, it
      is possible to disconnect the source during the creation of constraints
      and indexes and reduce the time it takes to perform the
      operation.</p>
</div>
</div>
<div class="section" title="Text File Usage">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="ttc_issues"></a>Text File Usage</h2>
</div>
</div>
</div>
<p>The following information applies to the usage of text
    tables.</p>
<div class="itemizedlist" title="Text File Issues">
<p class="title">
<b>Text File Issues</b>
</p>
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>With file databases, text fiile locations are restricted to
        below the directory that contains the database, unless the
        <code class="varname">textdb.allow_full_path</code> property is set true as a
        Java system property. This feature is for security, otherwise an admin
        database user may be able to open random files. The specified text
        source path is interpreted differently according to this property. By
        default, the path is interpreted as a relative path to the directory
        path of database files, it therefore cannot contain the double dot
        notation for parent directory. This path is then appended by the
        engine to the directory path to form a full path.</p>
<p>When the property is true, and the path starts with the forward
        slash or back slash, or the path contains a semicolon, the path is not
        appended to the directory path and is used as it is to open the file.
        In this usage the path is absolute.</p>
</li>
<li class="listitem">
<p>By default, all-in-memory databases cannot use text tables. To
        enable this capability the <code class="varname">textdb.allow_full_path</code>
        property must be set <code class="literal">true</code> as a Java system
        property. The text file path is used as submitted and interpreted as
        an absolute path as described above, or a path relative to the Java
        process execute path. These text tables are always read-only.</p>
</li>
<li class="listitem">
<p>Databases store in jars or as files on the classpath and opened
        with the res: protocol can reference read-only text files. These files
        are opened as resources. The file path is an absolute path beginning
        with a forward slash.</p>
</li>
<li class="listitem">
<p>Blank lines are allowed anywhere in the text file, and are
        ignored.</p>
</li>
<li class="listitem">
<p>It is possible to define a primary key, identity column, unique,
        foreign key and check constraints for text tables.</p>
</li>
<li class="listitem">
<p>When a table source file is used with the<code class="literal">
        ignore_first=true </code>option, the first, ignored line is
        replaced with a blank line after a SHUTDOWN COMPACT, unless the SOURCE
        HEADER statement has been used.</p>
</li>
<li class="listitem">
<p>An existing table source file may include CHARACTER fields that
        do not begin with the quote character but contain instances of the
        quote character. These fields are read as literal strings.
        Alternatively, if any field begins with the quote character, then it
        is interpreted as a quoted string that should end with the quote
        character and any instances of the quote character within the string
        is doubled. When any field containing the quote character or the
        separator is written out to the source file by the program, the field
        is enclosed in quote character and any instance of the quote character
        inside the field is doubled.</p>
</li>
<li class="listitem">
<p>Inserts or updates of CHARACTER type field values are allowed
        with strings that contains the linefeed or the carriage return
        character. This feature is disabled when both quoted and all_quoted
        properties are false.</p>
</li>
<li class="listitem">
<p>ALTER TABLE commands that add or drop columns or constraints
        (apart from check constraints) are not supported with text tables that
        are connected to a source. First use the SET TABLE &lt;name&gt; SOURCE
        OFF, make the changes, then turn the source ON.</p>
</li>
<li class="listitem">
<p>Use the default setting (quoted=true) for selective quoting of
        fields. Those fields that need quoting are quoted, other not.</p>
</li>
<li class="listitem">
<p>Use the quoted=false setting to avoid quoting of fields
        completely. With this setting any quote character is considered part
        of the text.</p>
</li>
<li class="listitem">
<p>Use the all_quoted=true setting to force all fields to be
        quoted.</p>
</li>
<li class="listitem">
<p>SHUTDOWN COMPACT results in a complete rewrite of text table
        sources that are open at the time. The settings for quoted and
        all_quoted are applied for the rewrite.</p>
</li>
</ul>
</div>
</div>
<div class="section" title="Text File Global Properties">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="ttc_global_props"></a>Text File Global Properties</h2>
</div>
</div>
</div>
<p>The database engine uses a set of defaults for text table
    properties. Each table's data source may override these defaults. It is
    also possible to override the defaults globally, so they apply to all text
    tables. The statement SET DATABASE TEXT TABLE DEFAULTS &lt;properties
    string&gt; can be used to override the default global properties. An
    example is given below:</p>
<pre class="programlisting"> SET DATABASE TEXT TABLE DEFAULTS 'all_quoted=true;encoding=UTF-8;cache_rows=10000;cache_size=2000'</pre>
<div class="itemizedlist" title="List of supported global properties">
<p class="title">
<b>List of supported global properties</b>
</p>
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>
<code class="literal">fs=,</code>
</p>
</li>
<li class="listitem">
<p>
<code class="literal">vs=,</code>
</p>
</li>
<li class="listitem">
<p>
<code class="literal">quoted=true</code>
</p>
</li>
<li class="listitem">
<p>
<code class="literal">all_quoted=false</code>
</p>
</li>
<li class="listitem">
<p>
<code class="literal">ignore_first=false</code>
</p>
</li>
<li class="listitem">
<p>
<code class="literal">encoding=ASCII</code>
</p>
</li>
<li class="listitem">
<p>
<code class="literal">cache_rows=1000</code>
</p>
</li>
<li class="listitem">
<p>
<code class="literal">cache_size=100</code>
</p>
</li>
<li class="listitem">
<p>
<code class="literal">textdb.allow_full_path=false (a system
        property)</code>
</p>
</li>
</ul>
</div>
</div>
<div class="section" title="Transactions">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="ttc_transactions"></a>Transactions</h2>
</div>
</div>
</div>
<p>Text tables fully support transactions. New or changed rows that
    have not been committed are not updated in the source file. Therefore the
    source file always contains committed rows.</p>
<p>However, text tables are not as resilient to machine crashes as
    other types of tables. If the crash happens while the text source is being
    written to, the text source may contain only some of the changes made
    during a committed transaction. With other types of tables, additional
    mechanisms ensure the integrity of the data and this situation will not
    arise.</p>
</div>
</div>
<div class="chapter" title="Chapter&nbsp;6.&nbsp;Access Control">
<div class="titlepage">
<div>
<div>
<h2 class="title">
<a name="accesscontrol-chapt"></a>Chapter&nbsp;6.&nbsp;Access Control</h2>
</div>
<div>
<div class="authorgroup">
<div class="author">
<h3 class="author">
<span class="firstname">Fred</span> <span class="surname">Toussi</span>
</h3>
<div class="affiliation">
<span class="orgname">The HSQL Development Group<br>
</span>
</div>
</div>
</div>
</div>
<div>
<p class="releaseinfo">$Revision: 3096 $</p>
</div>
<div>
<div class="legalnotice" title="Legal Notice">
<a name="N11CCC"></a>
<p>Copyright 2010-2012 Fred Toussi. Permission is granted to
      distribute this document without any alteration under the terms of the
      HSQLDB license. Additional permission is granted to the HSQL Development
      Group to distribute this document with or without alterations under the
      terms of the HSQLDB license.</p>
</div>
</div>
<div>
<p class="pubdate">2014-02-13 18:21:41-0500</p>
</div>
</div>
</div>
<div class="toc">
<p>
<b>Table of Contents</b>
</p>
<dl>
<dt>
<span class="section"><a href="#acc_overview">Overview</a></span>
</dt>
<dt>
<span class="section"><a href="#acc_auth_and_access_ctrl">Authorizations and Access Control</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#acc_built_in_roles_users">Built-In Roles and Users</a></span>
</dt>
<dt>
<span class="section"><a href="#acc_listing">Listing Users and Roles</a></span>
</dt>
<dt>
<span class="section"><a href="#acc_access_rights">Access Rights</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#acc_statements">Statements for
    Authorization and Access Control</a></span>
</dt>
</dl>
</div>
<div class="section" title="Overview">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="acc_overview"></a>Overview</h2>
</div>
</div>
</div>
<p>This chapter is about access control to database objects such as
    tables, inside the database engine. Other issues related to security
    include user authentication, password complexity and secure connections
    are covered in the <a class="link" href="#management-chapt" title="Chapter&nbsp;11.&nbsp;System Management">System Management</a> chapter and the <a class="link" href="#listeners-chapt" title="Chapter&nbsp;13.&nbsp;HyperSQL Network Listeners (Servers)">HyperSQL Network Listeners
    (Servers)</a>
    chapter.</p>
<p>Apart from schemas and their object, each HyperSQL catalog has USER
    and ROLE objects. These objects are collectively called
    <span class="emphasis"><em>authorizations</em></span>. Each AUTHORIZATION has some access
    rights on some of the schemas or the objects they contain. The persistent
    elements of an SQL environment are database objects</p>
<p>Authorizations names are stored in the database in the case-normal
    form. When connecting to a database via JDBC, the user name and password
    must match the case of this case-normal form.</p>
<p>When a user is created with the CREATE USER statement, if the user
    name is enclosed in double quotes, the exact name is used as the
    case-normal form. But if it is not enclosed in double quotes, the name is
    converted to uppercase and this uppercase version is stored in the
    database as the case-normal form.</p>
</div>
<div class="section" title="Authorizations and Access Control">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="acc_auth_and_access_ctrl"></a>Authorizations and Access Control</h2>
</div>
</div>
</div>
<p>In general, ROLE and USER objects simply control access to schema
    objects. This is the scope of the SQL Standard. However, there are special
    roles that allow the creation of USER and ROLE objects and also allow some
    special operations on the database as a whole. These roles are not defined
    by the Standard, which has left it to implementers to define such roles as
    they are needed for the particular SQL implementation.</p>
<p>A ROLE has a name a collection of zero or more other roles, plus
    some privileges (access rights). A USER has a name and a password. It
    similarly has a collection of zero or more roles plus some
    privileges.</p>
<p>USER objects existed in the SQL-92, but ROLE objects were introduced
    in SQL:1999. Originally it was intended that USER objects would normally
    be the same as the operating system USER objects and their authentication
    would be handled outside the SQL environment. The co-existence of ROLE and
    USER objects results in complexity. With the addition of ROLE objects,
    there is no rationale, other than legacy support, for granting privileges
    to USER objects directly. It is better to create roles and grant
    privileges to them, then grant the roles to USER objects.</p>
<p>The Standard effectively defines a special ROLE, named PUBLIC. All
    authorization have the PUBLIC role, which cannot be removed from them.
    Therefore any access right assigned to the PUBLIC role applies to all
    authorizations in the database. For many simple databases, it is adequate
    to create a single, non-admin user, then assign access rights to the
    pre-existing PUBLIC role. Access to INFORMATION_SCHEMA views is granted to
    PUBLIC, therefore these views are accessible to all. However, the contents
    of each view depends on the ROLE or USER (AUTHORIZATION) that is in force
    while accessing the view.</p>
<p>Each schema has a single AUTHORIZATION. This is commonly known as
    the <span class="emphasis"><em>owner</em></span> of the schema. All the objects in the
    schema inherit the schema owner. The schema owner can add objects to the
    schema, drop them or alter them.</p>
<p>By default, the objects in a schema can only be accessed by the
    schema owner. The schema owner can grant access rights on the objects to
    other users or roles.</p>
<a name="N11CFA" class="indexterm"></a>
<p>
<span class="bold"><strong>authorization
    identifier</strong></span>
</p>
<p>
<span class="emphasis"><em>authorization identifier</em></span>
</p>
<p>
<code class="literal">&lt;authorization identifier&gt; ::= &lt;role name&gt; |
    &lt;user name&gt;</code>
</p>
<p>Authorization identifiers share the same name-space within the
    database. The same name cannot be used for a USER and a ROLE.</p>
<div class="section" title="Built-In Roles and Users">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="acc_built_in_roles_users"></a>Built-In Roles and Users</h3>
</div>
</div>
</div>
<p>There are some pre-defined roles in each database; some defined by
      the SQL Standard, some by HyperSQL. These roles can be assigned to users
      (directly or via other, user-defined roles). In addition, there is the
      initial SYS user created with each new database. The initial user name
      and password is defined in the connection properties when the first
      connection to the database is made. In older versions of HSQLDB, this
      name was always SA. But in the latest version, the name can be defined
      as a different string.</p>
<a name="N11D11" class="indexterm"></a>
<p>
<span class="bold"><strong>PUBLIC</strong></span>
</p>
<p>
<span class="emphasis"><em>the PUBLIC role</em></span>
</p>
<p>The role that is assigned to all authorizations (roles and
      users) in the database. This role has access rights to all objects in
      the INFORMATION_SCHEMA. Any roles or rights granted to this role, are in
      effect granted to all users of the database.</p>
<a name="N11D1F" class="indexterm"></a>
<p>
<span class="bold"><strong>_SYSTEM</strong></span>
</p>
<p>
<span class="emphasis"><em>the _SYSTEM role</em></span>
</p>
<p>This role is the authorization for the pre-defined (system)
      objects in the database, including the INFORMATION_SCHEMA. This role
      cannot be assigned to any authorization.</p>
<a name="N11D2D" class="indexterm"></a>
<p>
<span class="bold"><strong>DBA</strong></span>
</p>
<p>
<span class="emphasis"><em>the DBA role (HyperSQL-specific)</em></span>
</p>
<p>This is a special role in HyperSQL. A user that has this role
      can perform all possible administrative tasks on the database. The DBA
      role can also act as a proxy for all the roles and users in the
      database. This means it can do everything the authorization for a schema
      can do, including dropping the schema or its objects, or granting rights
      on the schema objects to a grantee.</p>
<a name="N11D3B" class="indexterm"></a>
<p>
<span class="bold"><strong>CREATE_SCHEMA</strong></span>
</p>
<p>
<span class="emphasis"><em>the CREATE_SCHEMA role
      (HyperSQL-specific)</em></span>
</p>
<p>An authorization that has this role, can create schemas. The
      DBA authorization has this role and can grant it to other
      authorizations.</p>
<a name="N11D49" class="indexterm"></a>
<p>
<span class="bold"><strong>CHANGE_AUTHORIZATION</strong></span>
</p>
<p>
<span class="emphasis"><em>the CHANGE_AUTHORIZATION role
      (HyperSQL-specific)</em></span>
</p>
<p>A user that has this role, can change the authorization for the
      current session to another user. The other user cannot have the DBA role
      (otherwise, the original user would gain DBA privileges). The DBA
      authorization has this role and can grant it to other
      authorizations.</p>
<a name="N11D57" class="indexterm"></a>
<p>
<span class="bold"><strong>SYS User</strong></span>
</p>
<p>
<span class="emphasis"><em>the SYS user (HyperSQL-specific)</em></span>
</p>
<p>This user is automatically created with a new database and has
      the DBA role. This user name and its password are defined in the
      connection properties when connecting to the new database to create the
      database. As this user, it is possible to change the password, create
      other users and created new schema objects. The initial SYS user can be
      dropped by another user that has the DBA role. As a result, there is
      always at least one SYS user in the database.</p>
</div>
<div class="section" title="Listing Users and Roles">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="acc_listing"></a>Listing Users and Roles</h3>
</div>
</div>
</div>
<p>Tables in the INFORMATION_SCHEMA contain the list of users and
      roles for the database.</p>
<p>The SYSTEM_USERS tables contains the list of users, with some
      extra settings for each user. The AUTHORIZATIONS table contains a list
      of both users and roles.</p>
<p>Several other INFORMATION_SCHEMA tables list the privileges
      granted to users and roles on different database objects. Refer to the
      <a class="link" href="#databaseobjects-chapt" title="Chapter&nbsp;4.&nbsp;Schemas and Database Objects">Schemas and Database Objects</a> chapter for a list and
      description of the tables. Example below:</p>
<div class="informalexample">
<pre class="programlisting"> SELECT * FROM INFORMATION_SCHEMA.SYSTEM_USERS 
 SELECT * FROM INFORMATION_SCHEMA.TABLE_PRIVILEGES
</pre>
</div>
</div>
<div class="section" title="Access Rights">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="acc_access_rights"></a>Access Rights</h3>
</div>
</div>
</div>
<p>By default, the objects in a schema can only be accessed by the
      schema owner. But the schema owner can grant privileges (access rights)
      on the objects to other users or roles.</p>
<p>Things can get far more complex, because the grant of privileges
      can be made WITH GRANT OPTION. In this case, the role or user that has
      been granted the privilege can grant the privilege to other roles and
      users.</p>
<p>Privileges can also be revoked from users or roles.</p>
<p>The statements for granting and revoking privileges normally
      specify which privileges are granted or revoked. However, there is a
      shortcut, ALL PRIVILEGES, which means all the privileges that the
      <code class="literal">&lt;grantor&gt;</code> has on the schema object. The
      <code class="literal">&lt;grantor&gt;</code> is normally the CURRENT_USER of the
      session that issues the statement.</p>
<p>The user or role that is granted privileges is referred to as
      <code class="literal">&lt;grantee&gt;</code> for the granted privileges.</p>
<p>
<span class="bold"><strong>Table</strong></span>
</p>
<p>For tables, including views, privileges can be granted with
      different degrees of granularity. It is possible to grant a privilege on
      all columns of a table, or on specific columns of the table.</p>
<p>The DELETE privilege applies to the table, rather than its
      columns. It applies to all DELETE statements.</p>
<p>The SELECT, INSERT and UPDATE privileges may apply to all
      columns or to individual columns. These privileges determine whether the
      <code class="literal">&lt;grantee&gt;</code> can execute SQL data statements on
      the table.</p>
<p>The SELECT privilege designates the columns that can be
      referenced in SELECT statements, as well as the columns that are read in
      a DELETE or UPDATE statement, including the search condition.</p>
<p>The INSERT privilege designates the columns into which explicit
      values can be inserted. To be able to insert a row into the table, the
      user must therefore have the INSERT privilege on the table, or at least
      all the columns that do not have a default value.</p>
<p>The UPDATE privilege simply designates the table or the
      specific columns that can be updated.</p>
<p>The REFERENCES privilege allows the
      <code class="literal">&lt;grantee&gt;</code> to define a FOREIGN KEY constraint on
      a different table, which references the table or the specific columns
      designated for the REFERENCES privilege.</p>
<p>The TRIGGER privilege allows adding a trigger to the
      table.</p>
<p>
<span class="bold"><strong>Sequence, Type, Domain, Character Set,
      Collation, Transliteration,</strong></span>
</p>
<p>For these objects, only USAGE can be granted. The USAGE
      privilege is needed when object is referenced directly in an SQL
      statement.</p>
<p>
<span class="bold"><strong>Routine</strong></span>
</p>
<p>For routines, including procedures or functions, only EXECUTE
      privilege can be granted. This privilege is needed when the routine is
      used directly in an SQL statement.</p>
<p>
<span class="bold"><strong>Other Objects</strong></span>
</p>
<p>Other objects such as constraints and assertions are not used
      directly and there is no grantable privilege that refers to
      them.</p>
</div>
</div>
<div class="section" title="Statements for Authorization and Access Control">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="acc_statements"></a>Statements for
    Authorization and Access Control</h2>
</div>
</div>
</div>
<p>The statements listed below allow creation and destruction of USER
    and ROLE objects. The GRANT and REVOKE statements allow roles to be
    assigned to other roles or to users. The same statements are also used in
    a different form to assign privileges on schema objects to users and
    roles.</p>
<a name="N11DC1" class="indexterm"></a>
<p>
<a name="create_user-sql"></a><span class="bold"><strong>CREATE
    USER</strong></span>
</p>
<p>
<span class="emphasis"><em>user definition (HyperSQL)</em></span>
</p>
<p>
<code class="literal">&lt;user definition&gt; ::= CREATE USER &lt;user
    name&gt; PASSWORD &lt;password&gt; [ ADMIN ]</code>
</p>
<p>Define a new user and its password. <code class="literal">&lt;user
    name&gt;</code> is an SQL identifier. If it is double-quoted it is
    case-sensitive, otherwise it is turned to uppercase.
    <code class="literal">&lt;password&gt;</code> is a string enclosed with single quote
    characters and is case-sensitive. If <code class="literal">ADMIN</code> is
    specified, the DBA role is granted to the new user. Only a user with the
    DBA role can execute this statement.</p>
<a name="N11DDC" class="indexterm"></a>
<p>
<span class="bold"><strong>DROP USER</strong></span>
</p>
<p>
<span class="emphasis"><em>drop user statement (HyperSQL)</em></span>
</p>
<p>
<code class="literal">&lt;drop user statement&gt; ::= DROP USER &lt;user
    name&gt;</code>
</p>
<p>Drop (destroy) an existing user. If the specified user is the
    authorization for a schema, the schema is destroyed.</p>
<p>Only a user with the DBA role can execute this
    statement.</p>
<a name="N11DEF" class="indexterm"></a>
<p>
<span class="bold"><strong>ALTER USER ... SET
    PASSWORD</strong></span>
</p>
<p>
<span class="emphasis"><em>set the password for a user
    (HyperSQL)</em></span>
</p>
<p>
<code class="literal">&lt;alter user set password statement&gt; ::= ALTER USER
    &lt;user name&gt; SET PASSWORD &lt;password&gt;</code>
</p>
<p>Change the password of an existing user. <code class="literal">&lt;user
    name&gt;</code> is an SQL identifier. If it is double-quoted it is
    case-sensitive, otherwise it is turned to uppercase.
    <code class="literal">&lt;password&gt;</code> is a string enclosed with single quote
    characters and is case-sensitive.</p>
<p>Only a user with the DBA role can execute this command.</p>
<a name="N11E08" class="indexterm"></a>
<p>
<span class="bold"><strong>ALTER USER ... SET INITIAL
    SCHEMA</strong></span>
</p>
<p>
<span class="emphasis"><em>set the initial schema for a user
    (HyperSQL)</em></span>
</p>
<p>
<code class="literal">&lt;alter user set initial schema statement&gt; ::=
    ALTER USER &lt;user name&gt; SET INITIAL SCHEMA &lt;schema name&gt; |
    DEFAULT</code>
</p>
<p>Change the initial schema for a user. The initial schema is the
    schema used by default for SQL statements issued during a session. If
    <code class="literal">DEFAULT</code> is used, the default initial schema for all
    users is used as the initial schema for the user. The SET SCHEMA command
    allows the user to change the schema for the duration of the
    session.</p>
<p>Only a user with the DBA role can execute this
    statement.</p>
<a name="N11E1E" class="indexterm"></a>
<p>
<span class="bold"><strong>ALTER USER ... SET
    LOCAL</strong></span>
</p>
<p>
<span class="emphasis"><em>set the user authentication as local
    (HyperSQL)</em></span>
</p>
<p>
<code class="literal">&lt;alter user set local&gt; ::= ALTER USER &lt;user
    name&gt; SET LOCAL { TRUE | FALSE }</code>
</p>
<p>Sets the authentication method for the user as local. This
    statement has an effect only when external authentication with role names
    is enabled. In this method of authentication, users created in the
    database are ignored and an external authentication mechanism, such as
    LDAP is used. This statement is used if you want to use local, password
    authentication for a specific user.</p>
<p>Only a user with the DBA role can execute this
    statement.</p>
<a name="N11E31" class="indexterm"></a>
<p>
<a name="set_password-sql"></a><span class="bold"><strong>SET
    PASSWORD</strong></span>
</p>
<p>
<span class="emphasis"><em>set password statement (HyperSQL)</em></span>
</p>
<p>
<code class="literal">&lt;set password statement&gt; ::= SET PASSWORD
    &lt;password&gt;</code>
</p>
<p>Set the password for the current user.
    <code class="literal">&lt;password&gt;</code> is a string enclosed with single quote
    characters and is case-sensitive.</p>
<a name="N11E46" class="indexterm"></a>
<p>
<span class="bold"><strong>SET INITIAL SCHEMA</strong></span>
</p>
<p>
<span class="emphasis"><em>set the initial schema for the current user
    (HyperSQL)</em></span>
</p>
<p>
<code class="literal">&lt;set initial schema statement&gt; ::= SET INITIAL
    SCHEMA &lt;schema name&gt; | DEFAULT</code>
</p>
<p>Change the initial schema for the current user. The initial
    schema is the schema used by default for SQL statements issued during a
    session. If <code class="literal">DEFAULT</code> is used, the default initial schema
    for all users is used as the initial schema for the current user. The
    separate SET SCHEMA command allows the user to change the schema for the
    duration of the session. See also the <a class="link" href="#sessions-chapt" title="Chapter&nbsp;3.&nbsp;Sessions and Transactions">Sessions and Transactions</a> chapter.</p>
<a name="N11E5F" class="indexterm"></a>
<p>
<span class="bold"><strong>SET DATABASE DEFAULT INITIAL
    SCHEMA</strong></span>
</p>
<p>
<span class="emphasis"><em>set the default initial schema for all users
    (HyperSQL)</em></span>
</p>
<p>
<code class="literal">&lt;set database default initial schema statement&gt;
    ::= SET DATABASE DEFAULT INITIAL SCHEMA &lt;schema
    name&gt;</code>
</p>
<p>Sets the initial schema for new users. This schema can later be
    changed with the <code class="literal">&lt;set initial schema statement&gt;</code>
    command.</p>
<a name="N11E73" class="indexterm"></a>
<p>
<span class="bold"><strong>CREATE ROLE</strong></span>
</p>
<p>
<span class="emphasis"><em>role definition</em></span>
</p>
<p>
<code class="literal">&lt;role definition&gt; ::= CREATE ROLE &lt;role
    name&gt; [ WITH ADMIN &lt;grantor&gt; ]</code>
</p>
<p>Defines a new role. Initially the role has no rights, except
    those of the PUBLIC role. Only a user with the DBA role can execute this
    command.</p>
<a name="N11E84" class="indexterm"></a>
<p>
<span class="bold"><strong>DROP ROLE</strong></span>
</p>
<p>
<span class="emphasis"><em>drop role statement</em></span>
</p>
<p>
<code class="literal">&lt;drop role statement&gt; ::= DROP ROLE &lt;role
    name&gt;</code>
</p>
<p>Drop (destroy) a role. If the specified role is the authorization
    for a schema, the schema is destroyed. Only a user with the DBA role can
    execute this statement.</p>
<a name="N11E95" class="indexterm"></a>
<p>
<span class="bold"><strong>GRANTED BY</strong></span>
</p>
<p>
<span class="emphasis"><em>grantor determination</em></span>
</p>
<p>
<code class="literal">GRANTED BY &lt;grantor&gt;</code>
</p>
<p>
<code class="literal">&lt;grantor&gt; ::= CURRENT_USER |
    CURRENT_ROLE</code>
</p>
<p>The authorization that is granting or revoking a role or
    privileges. The optional <code class="literal">GRANTED BY &lt;grantor&gt;</code>
    clause can be used in various statements that perform GRANT or REVOKE
    actions. If the clause is not used, the authorization is CURRENT_USER.
    Otherwise, it is the specified authorization.</p>
<a name="N11EAC" class="indexterm"></a>
<p>
<span class="bold"><strong>GRANT</strong></span>
</p>
<p>
<span class="emphasis"><em>grant privilege statement</em></span>
</p>
<p>
<code class="literal">&lt;grant privilege statement&gt; ::= GRANT
    &lt;privileges&gt; TO &lt;grantee&gt; [ { &lt;comma&gt; &lt;grantee&gt;
    }... ] [ WITH GRANT OPTION ] [ GRANTED BY &lt;grantor&gt;
    ]</code>
</p>
<p>Assign privileges on schema objects to roles or users. Each
    <code class="literal">&lt;grantee&gt;</code> is a role or a user. If <code class="literal">[ WITH
    GRANT OPTION ]</code> is specified, then the
    <code class="literal">&lt;grantee&gt;</code> can assign the privileges to other
    <code class="literal">&lt;grantee&gt;</code> objects.</p>
<p>
<code class="literal">&lt;privileges&gt; ::= &lt;object privileges&gt; ON
    &lt;object name&gt;</code>
</p>
<p>
<code class="literal">&lt;object name&gt; ::= [ TABLE ] &lt;table name&gt; |
    DOMAIN &lt;domain name&gt; | COLLATION &lt;collation name&gt; | CHARACTER
    SET &lt;character set name&gt; | TRANSLATION &lt;transliteration name&gt;
    | TYPE &lt;user-defined type name&gt; | SEQUENCE &lt;sequence generator
    name&gt; | &lt;specific routine designator&gt; | ROUTINE &lt;routine
    name&gt; | FUNCTION &lt;function name&gt; | PROCEDURE &lt;procedure
    name&gt;</code>
</p>
<p>
<code class="literal">&lt;object privileges&gt; ::= ALL PRIVILEGES |
    &lt;action&gt; [ { &lt;comma&gt; &lt;action&gt; }... ]</code>
</p>
<p>
<code class="literal">&lt;action&gt; ::= SELECT | SELECT &lt;left paren&gt;
    &lt;privilege column list&gt; &lt;right paren&gt; | DELETE | INSERT [
    &lt;left paren&gt; &lt;privilege column list&gt; &lt;right paren&gt; ] |
    UPDATE [ &lt;left paren&gt; &lt;privilege column list&gt; &lt;right
    paren&gt; ] | REFERENCES [ &lt;left paren&gt; &lt;privilege column
    list&gt; &lt;right paren&gt; ] | USAGE | TRIGGER |
    EXECUTE</code>
</p>
<p>
<code class="literal">&lt;privilege column list&gt; ::= &lt;column name
    list&gt;</code>
</p>
<p>
<code class="literal">&lt;grantee&gt; ::= PUBLIC | &lt;authorization
    identifier&gt;</code>
</p>
<p>The <code class="literal">&lt;object privileges&gt;</code> that can be used
    depend on the type of the <code class="literal">&lt;object name&gt;</code>. These
    are discussed in the previous section. For a table, if
    <code class="literal">&lt;privilege column list&gt;</code> is not specified, then
    the privilege is granted on the table, which includes all of its columns
    and any column that may be added to it in the future. For routines, the
    name of the routine can be specified in two ways, either as the generic
    name as the specific name. HyperSQL allows referencing all overloaded
    versions of a routine at the same time, using its name. This differs from
    the SQL Standard which requires the use of <code class="literal">&lt;specific routine
    designator&gt;</code> to grant privileges separately on each different
    signature of the routine.</p>
<p>Each <code class="literal">&lt;grantee&gt;</code> is the name of a role or
    a user. Examples of GRANT statement are given below:</p>
<div class="informalexample">
<pre class="programlisting"> GRANT ALL ON SEQUENCE aSequence TO roleOrUser 
 GRANT SELECT ON aTable TO roleOrUser  
 GRANT SELECT, UPDATE ON aTABLE TO roleOrUser1, roleOrUser2
 GRANT SELECT(columnA, columnB), UPDATE(columnA, columnB) ON TABLE aTable TO roleOrUser
 GRANT EXECUTE ON SPECIFIC ROUTINE aroutine_1234 TO rolOrUser
</pre>
</div>
<p>As mentioned in the general discussion, it is better to define a
    role for the collection of all the privileges required by an application.
    This role is then granted to any user. If further changes are made to the
    privileges of this role, they are automatically reflected in all the users
    that have the role.</p>
<a name="N11EF3" class="indexterm"></a>
<p>
<span class="bold"><strong>GRANT</strong></span>
</p>
<p>
<span class="emphasis"><em>grant role statement</em></span>
</p>
<p>
<code class="literal">&lt;grant role statement&gt; ::= GRANT &lt;role name&gt;
    [ { &lt;comma&gt; &lt;role name&gt; }... ] TO &lt;grantee&gt; [ {
    &lt;comma&gt; &lt;grantee&gt; }... ] [ WITH ADMIN OPTION ] [ GRANTED BY
    &lt;grantor&gt; ]</code>
</p>
<p>Assign roles to roles or users. One or more roles can be assigned
    to one or more <code class="literal">&lt;grantee&gt;</code> objects. A
    <code class="literal">&lt;grantee&gt;</code> is a user or a role. If the <code class="literal">[
    WITH ADMIN OPTION ]</code> is specified, then each
    <code class="literal">&lt;grantee&gt;</code> can grant the newly assigned roles to
    other grantees. An example of user and role creation with grants is given
    below:</p>
<div class="informalexample">
<pre class="programlisting"> CREATE USER appuser
 CREATE ROLE approle
 GRANT approle TO appuser
 GRANT SELECT, UPDATE ON TABLE atable TO approle
 GRANT USAGE ON SEQUENCE asequence to approle
 GRANT EXECUTE ON ROUTINE aroutine TO approle
</pre>
</div>
<a name="N11F13" class="indexterm"></a>
<p>
<span class="bold"><strong>REVOKE privilege</strong></span>
</p>
<p>
<span class="emphasis"><em>revoke statement</em></span>
</p>
<p>
<code class="literal">&lt;revoke privilege statement&gt; ::= REVOKE [ GRANT
    OPTION FOR ] &lt;privileges&gt; FROM &lt;grantee&gt; [ { &lt;comma&gt;
    &lt;grantee&gt; }... ] [ GRANTED BY &lt;grantor&gt; ] RESTRICT |
    CASCADE</code>
</p>
<p>Revoke privileges from a user or role.</p>
<a name="N11F24" class="indexterm"></a>
<p>
<span class="bold"><strong>REVOKE role</strong></span>
</p>
<p>
<span class="emphasis"><em>revoke role statement</em></span>
</p>
<p>
<code class="literal">&lt;revoke role statement&gt; ::= REVOKE [ ADMIN OPTION
    FOR ] &lt;role revoked&gt; [ { &lt;comma&gt; &lt;role revoked&gt; }... ]
    FROM &lt;grantee&gt; [ { &lt;comma&gt; &lt;grantee&gt; }... ] [ GRANTED BY
    &lt;grantor&gt; ] RESTRICT | CASCADE</code>
</p>
<p>
<code class="literal">&lt;role revoked&gt; ::= &lt;role
    name&gt;</code>
</p>
<p>Revoke a role from users or roles.</p>
</div>
</div>
<div class="chapter" title="Chapter&nbsp;7.&nbsp;Data Access and Change">
<div class="titlepage">
<div>
<div>
<h2 class="title">
<a name="dataaccess-chapt"></a>Chapter&nbsp;7.&nbsp;Data Access and Change</h2>
</div>
<div>
<div class="authorgroup">
<div class="author">
<h3 class="author">
<span class="firstname">Fred</span> <span class="surname">Toussi</span>
</h3>
<div class="affiliation">
<span class="orgname">The HSQL Development Group<br>
</span>
</div>
</div>
</div>
</div>
<div>
<p class="releaseinfo">$Revision: 5240 $</p>
</div>
<div>
<div class="legalnotice" title="Legal Notice">
<a name="N11F5C"></a>
<p>Copyright 2010-2012 Fred Toussi. Permission is granted to
      distribute this document without any alteration under the terms of the
      HSQLDB license. Additional permission is granted to the HSQL Development
      Group to distribute this document with or without alterations under the
      terms of the HSQLDB license.</p>
</div>
</div>
<div>
<p class="pubdate">2014-02-13 18:21:41-0500</p>
</div>
</div>
</div>
<div class="toc">
<p>
<b>Table of Contents</b>
</p>
<dl>
<dt>
<span class="section"><a href="#dac_overview">Overview</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_jdbc_cursors_result_sets">Cursors And Result Sets</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#dac_jdbc_columns_rows">Columns and Rows</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_jdbc_cursor_navigation">Navigation</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_jdbc_cursor_updatability">Updatability</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_jdbc_cursor_sensitivity">Sensitivity</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_jdbc_cursor_holdability">Holdability</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_jdbc_autocommit">Autocommit</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_jdbc_overview">JDBC Overview</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_jdbc_parameters">JDBC Parameters</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_jdbc_data_change">JDBC and Data Change Statements</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_jdbc_callable_statement">JDBC Callable Statement</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_jdbc_return_values">JDBC Returned Values</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_declare_cursor">Cursor Declaration</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#dac_syntax_elements">Syntax Elements</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#dac_literals">Literals</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_sql_references">References, etc.</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_value_expression">Value Expression</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_sql_predicates">Predicates</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_aggregate_funcs">Aggregate Functions</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_other_syntax_elements">Other Syntax Elements</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#dac_data_access_statements">Data Access Statements</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#dac_sql_select_statement">Select Statement</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_table">Table</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_subquery">Subquery</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_query_specification">Query Specification</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_table_expression">Table Expression</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_joined_table">Joined Table</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_selection">Selection</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_projection">Projection</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_computed_columns">Computed Columns</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_naming">Naming</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_grouping_operations">Grouping Operations</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_aggregation">Aggregation</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_set_operations">Set Operations</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_with_clause">With Clause and Recursive Queries</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_query_expression">Query Expression</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_ordering">Ordering</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_slicing">Slicing</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#dac_data_change_statements">Data Change Statements</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#dac_delete_statement">Delete Statement</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_truncate_statement">Truncate Statement</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_insert_statement">Insert Statement</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_update_statement">Update Statement</a></span>
</dt>
<dt>
<span class="section"><a href="#dac_merge_statement">Merge Statement</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#dac_diagnostics_state">Diagnostics and State</a></span>
</dt>
</dl>
</div>
<div class="section" title="Overview">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="dac_overview"></a>Overview</h2>
</div>
</div>
</div>
<p>HyperSQL data access and data change statements are fully compatible
    with the latest SQL:2008 Standard. There are a few extensions and some
    relaxation of rules, but these do not affect statements that are written
    to the Standard syntax. There is full support for classic SQL, as
    specified by SQL-92, and many enhancements added in later versions of the
    standard.</p>
</div>
<div class="section" title="Cursors And Result Sets">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="dac_jdbc_cursors_result_sets"></a>Cursors And Result Sets</h2>
</div>
</div>
</div>
<p>An SQL statement can executed in two ways. One way is to use the
    <code class="classname">java.sql.Statement</code> interface. The Statement object
    can be reused to execute completely different SQL statements.
    Alternatively a <code class="classname">PreparedStatment</code> can be used to
    execute an SQL statement repeatedly, and the statements can be
    parameterized. Using either form, if the SQL statement is a query
    expression, a <code class="classname">ResultSet</code> is returned.</p>
<p>In SQL, when a query expression (SELECT or similar SQL statement) is
    executed, an ephemeral table is created. When this table is returned to
    the application program, it is returned as a result set, which is accessed
    row-by-row by a cursor. A JDBC <code class="classname">ResultSet</code> represents
    an SQL result set and its cursor.</p>
<p>The minimal definition of a cursor is a list of rows with a position
    that can move forward. Some cursors also allow the position to move
    backwards or jump to any position in the list.</p>
<p>An SQL cursor has several attributes. These attributes depend on the
    query expression. Some of these attributes can be overridden by specifying
    qualifiers in the SQL statement or by specifying values for the parameters
    of the JDBC <code class="classname">Statement</code> or
    <code class="classname">PreparedStatement</code>.</p>
<div class="section" title="Columns and Rows">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_jdbc_columns_rows"></a>Columns and Rows</h3>
</div>
</div>
</div>
<p>The columns of the rows of the result set are determined by the
      query expression. The number of columns and the type and name
      characteristics of each column are known when the query expression is
      compiled and before its execution. This metadata information remains
      constant regardless of changes to the contents of the tables used in the
      query expression. The metadata for the JDBC
      <code class="classname">ResultSet</code> is in the form of a
      <code class="classname">ResultSetMetaData</code> object. Various methods of the
      <code class="classname">ResultSetMetaData</code> interface return different
      properties of each column of the
      <code class="classname">ResultSet</code>.</p>
<p>A result set may contain 0 or more rows. The rows are determined
      by the execution of the query expression.</p>
<p>The <code class="methodname">setMaxRows(int)</code> method of JDBC
      <code class="classname">Statement</code> allows limiting the number of rows
      returned by the statement. This limit is conceptually applied after the
      result has been built, and the excess rows are discarded.</p>
</div>
<div class="section" title="Navigation">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_jdbc_cursor_navigation"></a>Navigation</h3>
</div>
</div>
</div>
<p>A cursor is either scrollable or not. Scrollable cursors allow
      accessing rows by absolute or relative positioning. No-scroll cursors
      only allow moving to the next row. The cursor can be optionally declared
      with the SQL qualifiers SCROLL, or NO SCROLL. The JDBC statement
      parameter can be specified as: TYPE_FORWARD_ONLY and
      TYPE_SCROLL_INSENSITIVE. The JDBC type TYPE_SCROLL_SENSITIVE is not
      supported by HSQLDB.</p>
<p>The default is NO SCROLL or TYPE_FORWARD_ONLY.</p>
<p>When a JDBC <code class="classname">ResultSet</code> is opened, it is
      positioned before the first row. Using the
      <code class="methodname">next()</code> method the position is moved to the
      first row. While the <code class="classname">ResultSet</code> is positioned on a
      row, various getter methods can be used to access the columns of the
      row.</p>
</div>
<div class="section" title="Updatability">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_jdbc_cursor_updatability"></a>Updatability</h3>
</div>
</div>
</div>
<p>The result returned by some query expressions is updatable. HSQLDB
      supports core SQL updatability features, plus some enhancements from the
      SQL optional features.</p>
<p>A query expression is updatable if it is a SELECT from a single
      underlying base table (or updatable view) either directly or indirectly.
      A SELECT statement featuring DISTINCT or GROUP BY or FETCH, LIMIT,
      OFFSET is not updatable. In an updatable query expression, one or more
      columns are updatable. An updatable column is a column that can be
      traced directly to the underlying table. Therefore, columns that contain
      expressions are not updatable. Examples of updatable query expressions
      are given below. The view V is updatable when its query expression is
      updatable. The SELECT statement from this view is also updatable:</p>
<pre class="programlisting"> SELECT A, B FROM T WHERE C &gt; 5
 SELECT A, B FROM (SELECT * FROM T WHERE C &gt; 10) AS TT WHERE TT.B &lt;10
 CREATE VIEW V(X,Y) AS SELECT A, B FROM T WHERE C &gt; 0 AND B &lt; 10
 SELECT X FROM V WHERE Y = 5
</pre>
<p>If a cursor is declared with the SQL qualifier, <code class="literal">FOR
      UPDATE OF &lt;column name list&gt;</code>, then only the stated
      columns in the result set become updatable. If any of the stated columns
      is not actually updatable, then the cursor declaration will not
      succeed.</p>
<p>If the SQL qualifier, FOR UPDATE is used, then all the updatable
      columns of the result set become updatable.</p>
<p>If a cursor is declared with FOR READ ONLY, then it is not
      updatable.</p>
<p>In HSQLDB, if FOR READ ONLY or FOR UPDATE is not used then all the
      updatable columns of the result set become updatable. This relaxes the
      SQL standard rule that in this case limits updatability to only simply
      updatable SELECT statements (where all columns are updatable).</p>
<p>In JDBC, CONCUR_READ_ONLY or CONCUR_UPDATABLE can be specified for
      the <code class="classname">Statement</code> parameter. CONCUR_UPDATABLE is
      required if the returning ResultSet is to be updatable. If
      CONCUR_READ_ONLY, which is the default, is used, then even an updatable
      ResultSet becomes read-only.</p>
<p>When a <code class="classname">ResultSet</code> is updatable, various
      setter methods can be used to modify the column values. The names of the
      setter methods begin with "update". After all the updates on a row are
      done, the <code class="methodname">updateRow()</code> method must be called to
      finalise the row update.</p>
<p>An updatable <code class="classname">ResultSet</code> may or may not be
      insertable-into. In an insertable <code class="classname">ResultSet</code>, all
      columns of the result are updatable and any column of the base table
      that is not in the result must be a generated column or have a default
      value.</p>
<p>In the <code class="classname">ResultSet</code> object, a special
      pseudo-row, called the insert row, is used to populate values for
      insertion into the <code class="classname">ResultSet</code> (and consequently,
      into the base table). The setter methods must be used on all the
      columns, followed by a call to
      <code class="methodname">insertRow()</code>.</p>
<p>Individual rows from all updatable result sets can be deleted one
      at a time. The <code class="methodname">deleteRow()</code> is called when the
      <code class="classname">ResultSet</code> is positioned on a row.</p>
<p>While using an updatable ResultSet to modify data, it is
      recommended not to change the same data using another ResultSet and not
      to execute SQL data change statements that modify the same data.</p>
</div>
<div class="section" title="Sensitivity">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_jdbc_cursor_sensitivity"></a>Sensitivity</h3>
</div>
</div>
</div>
<p>The sensitivity of the cursor relates to visibility of changes
      made to the data by the same transaction but without using the given
      cursor. While the result set is open, the same transaction may use
      statements such as INSERT or UPDATE, and change the data of the tables
      from which the result set data is derived. A cursor is SENSITIVE if it
      reflects those changes. It is INSENSITIVE if it ignores such changes. It
      is ASENSITIVE if behaviour is implementation dependent.</p>
<p>The SQL default is ASENSITIVE, i.e., implantation
      dependent.</p>
<p>In HSQLDB all cursors are INSENSITIVE. They do not reflect changes
      to the data made by other statements.</p>
</div>
<div class="section" title="Holdability">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_jdbc_cursor_holdability"></a>Holdability</h3>
</div>
</div>
</div>
<p>A cursor is holdable if the result set is not automatically closed
      when the current transaction is committed. Holdability can be specified
      in the cursor declaration using the SQL qualifiers WITH HOLD or WITHOUT
      HOLD.</p>
<p>In JDBC, holdability is specified using either of the following
      values for the Statement parameter: HOLD_CURSORS_OVER_COMMIT, or
      CLOSE_CURSORS_AT_COMMIT.</p>
<p>The SQL default is WITHOUT HOLD.</p>
<p>The JDBC default for HSQLDB result sets is WITH HOLD for read-only
      result sets and WITHOUT HOLD for updatable result sets.</p>
<p>If the holdability of a <code class="classname">ResultSet</code> is
      specified in a conflicting manner in the SQL statement and the JDBC
      <code class="classname">Statement</code> object, the JDBC setting takes
      precedence.</p>
</div>
<div class="section" title="Autocommit">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_jdbc_autocommit"></a>Autocommit</h3>
</div>
</div>
</div>
<p>The autocommit property of a connection is a feature of JDBC and
      ODBC and is not part of the SQL Standard. In autocommit mode, all
      transactional statements are followed by an implicit commit. In
      autocommit mode, all <code class="classname">ResultSet</code> objects are
      read-only and holdable.</p>
</div>
<div class="section" title="JDBC Overview">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_jdbc_overview"></a>JDBC Overview</h3>
</div>
</div>
</div>
<p>The JDBC settings, ResultSet.CONCUR_READONLY and
      ResultSet.CONCUR_UPDATABLE are the available alternatives for read-only
      or updatability. The default is ResultSet.CONCUR_READONLY.</p>
<p>The JDBC settings, ResultSet.TYPE_FORWARD_ONLY,
      ResultSet.TYPE_SCROLL_INSENSITIVE, ResultSet.TYPE_SCROLL_SENSITIVE are
      the available alternatives for both scrollability (navigation) and
      sensitivity. HyperSQL does not support ResultSet.TYPE_SCROLL_SENSITIVE.
      The two other alternatives can be used for both updatable and read-only
      result sets.</p>
<p>The JDBC settings ResultSet.CLOSE_CURSORS_AT_COMMIT and
      ResultSet.HOLD_CURSORS_OVER_COMMIT are the alternatives for the lifetime
      of the result set. The default is ResultSet.CLOSE_CURSORS_AT_COMMIT. The
      other setting can only be used for read-only result sets.</p>
<p>Examples of creating statements for updatable result sets are
      given below:</p>
<pre class="programlisting"> Connection c = newConnection();
 Statement st;
 c.setAutoCommit(false);
 st = c.createStatement(ResultSet.TYPE_FORWARD_ONLY, ResultSet.CONCUR_UPDATABLE);
 st = c.createStatement(ResultSet.TYPE_SCROLL_INSENSITIVE, ResultSet.CONCUR_UPDATABLE);</pre>
</div>
<div class="section" title="JDBC Parameters">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_jdbc_parameters"></a>JDBC Parameters</h3>
</div>
</div>
</div>
<p>When a JDBC PreparedStatement or CallableStatement is used with an
      SQL statement that contains dynamic parameters, the data types of the
      parameters are resolved and determined by the engine when the statement
      is prepared. The SQL Standard has detailed rules to determine the data
      types and imposes limits on the maximum length or precision of the
      parameter. HyperSQL applies the standard rules with two exceptions for
      parameters with String and BigDecimal Java types. HyperSQL ignores the
      limits when the parameter value is set, and only enforces the necessary
      limits when the PreparedStatement is executed. In all other cases,
      parameter type limits are checked and enforce when the parameter is
      set.</p>
<p>In the example below the setString() calls do not raise an
      exception, but one of the execute() statements does.</p>
<pre class="programlisting"> // table definition: CREATE TABLE T (NAME VARCHAR(12), ...)
 Connection c = newConnection();
 PreparedStatement st = c.prepareStatement("SELECT * FROM T WHERE NAME = ?");
 // type of the parameter is VARCHAR(12), which limits length to 12 characters
 st.setString(1, "Eyjafjallajokull"); // string is longer than type, but no exception is raised here
 set.execute(); // executes with no exception and does not find any rows

 // but if an UPDATE is attempted, an exception is raised
 st = c.prepareStatement("UPDATE T SET NAME = ? WHERE ID = 10");
 st.setString(1, "Eyjafjallajokull"); // string is longer than type, but no exception is raised here
 st.execute(); // exception is thrown when HyperSQL checks the value for update

</pre>
<p>All of the above also applies to setting the values in new and
      updated rows in updatable ResultSet objects.</p>
<p>JDBC parameters can be set with any compatible type, as supported
      by the JDBC specification. For CLOB and BLOB types, you can use streams,
      or create instances of BLOB or CLOB before assigning them to the
      parameters. You can even use CLOB or BLOB objects returned from
      connections to other RDBMS servers. The Connection.createBlob() and
      createClob() methods can be used to create the new LOBs. For very large
      LOB's the stream methods are preferable as they use less memory.</p>
<p>For array parameters, you must use a
      <code class="classname">java.sql.Array</code> object that contains the array
      elements before assigning to JDBC parameters. The
      <code class="code">Connection.createArrayOf(...)</code> method can be used to create
      a new object, or you can use an Array returned from connections to other
      RDBMS servers.</p>
</div>
<div class="section" title="JDBC and Data Change Statements">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_jdbc_data_change"></a>JDBC and Data Change Statements</h3>
</div>
</div>
</div>
<p>Data change statements, also called data manipulation statements
      (DML) such as INSERT, UPDATE, MERGE can be called with different
      executeUpdate() methods of java.sql.Statement and
      java.sql.PreparedStatement. Some of these methods allow you to specify
      how values for generated columns of the table are returned. These
      methods are documented in the JavaDoc for org.hsqldb.jdbc.JDBCStatement
      and org.hsqldb.jdbc.JDBCPreparedStatement. HyperSQL can return not just
      the generated columns, but any set of columns of the table. You can use
      this to retrieve the columns values that may be modified by a BEFORE
      TRIGGER on the table.</p>
</div>
<div class="section" title="JDBC Callable Statement">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_jdbc_callable_statement"></a>JDBC Callable Statement</h3>
</div>
</div>
</div>
<p>The JDBC CallableStatement interface is used to call Java or SQL
      procedures that have been defined in the database. The SQL statement in
      the form of CALL procedureName ( ... ) with constant value arguments or
      with parameter markers. Note that you must use a parameter marker for
      OUT and INOUT arguments of the procedure you are calling. The OUT
      arguments should not be set before executing the callable
      statement.</p>
<p>After executing the statement, you can retrieve the OUT and INOUT
      parameters with the appropriate getXXX() method.</p>
<p>Procedures can also return one or more result sets. You should
      call the getResultSet() and getMoreResults() methods to retrieve the
      result sets one by one.</p>
<p>SQL functions can also return a table. You can call such functions
      the same way as procedures and retrieve the table as a ResultSet.</p>
</div>
<div class="section" title="JDBC Returned Values">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_jdbc_return_values"></a>JDBC Returned Values</h3>
</div>
</div>
</div>
<p>The methods of the JDBC ResultSet interface can be used to return
      values and to convert value to different types as supported by the JDBC
      specification.</p>
<p>When a CLOB and BLOB object is returned from a ResultSet, no data
      is transferred until the data is read by various methods of
      java.sql.CLOB and java.sql.BLOB. Data is streamed in large blocks to
      avoid excessive memory use.</p>
<p>Array objects are returned as instances of java.sql.Array.</p>
</div>
<div class="section" title="Cursor Declaration">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_declare_cursor"></a>Cursor Declaration</h3>
</div>
</div>
</div>
<p>The DECLARE CURSOR statement is used within an SQL PROCEDURE body.
      In the early releases of HyperSQL 2.0, the cursor is used only to return
      a result set from the procedure. Therefore the cursor must be declared
      WITH RETURN and can only be READ ONLY.</p>
<a name="N1205E" class="indexterm"></a>
<p>
<span class="bold"><strong>DECLARE CURSOR</strong></span>
</p>
<p>
<span class="emphasis"><em>declare cursor statement</em></span>
</p>
<p>
<code class="literal">&lt;declare cursor&gt; ::= DECLARE &lt;cursor
      name&gt;</code>
</p>
<p>
<code class="literal">[ { SENSITIVE | INSENSITIVE | ASENSITIVE } ] [ { SCROLL |
      NO SCROLL } ] </code>
</p>
<p>
<code class="literal">CURSOR [ { WITH HOLD | WITHOUT HOLD } ] [ { WITH RETURN |
      WITHOUT RETURN } ]</code>
</p>
<p>
<code class="literal">FOR &lt;query expression&gt;</code>
</p>
<p>
<code class="literal">[ FOR { READ ONLY | UPDATE [ OF &lt;column name list&gt;
      ] } ]</code>
</p>
<p>The query expression is a SELECT statement or similar, and is
      discussed in the rest of this chapter. In the example below a cursor is
      declared for a SELECT statement. It is later opened to create the result
      set. The cursor is specified WITHOUT HOLD, so the result set is not kept
      after a commit. Use WITH HOLD to keep the result set. Note that you need
      to declare the cursor WITH RETURN as it is returned by the
      <code class="classname">CallableStatement</code>.</p>
<pre class="programlisting"> DECLARE thiscursor SCROLL CURSOR WITHOUT HOLD WITH RETURN FOR SELECT * FROM INFORMATION_SCHEMA.TABLES;
 --
 OPEN thiscursor;
</pre>
</div>
</div>
<div class="section" title="Syntax Elements">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="dac_syntax_elements"></a>Syntax Elements</h2>
</div>
</div>
</div>
<p>The syntax elements that can be used in data access and data change
    statements are described in this section. The SQL Standard has a very
    extensive set of definitions for these elements. The BNF definitions given
    here are sometimes simplified.</p>
<div class="section" title="Literals">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_literals"></a>Literals</h3>
</div>
</div>
</div>
<p>Literals are used to express constant values. The general type of
      a literal is known by its format. The specific type is based on
      conventions.</p>
<a name="N1208C" class="indexterm"></a>
<p>
<span class="bold"><strong>unicode escape
      elements</strong></span>
</p>
<p>
<span class="emphasis"><em>unicode escape elements</em></span>
</p>
<p>
<code class="literal">&lt;Unicode escape specifier&gt; ::= [ UESCAPE
      &lt;quote&gt;&lt;Unicode escape character&gt;&lt;quote&gt; ]
      </code>
</p>
<p>
<code class="literal">&lt;Unicode escape value&gt; ::= &lt;Unicode 4 digit
      escape value&gt; | &lt;Unicode 6 digit escape value&gt; | &lt;Unicode
      character escape value&gt;</code>
</p>
<p>
<code class="literal">&lt;Unicode 4 digit escape value&gt; ::= &lt;Unicode
      escape
      character&gt;&lt;hexit&gt;&lt;hexit&gt;&lt;hexit&gt;&lt;hexit&gt;</code>
</p>
<p>
<code class="literal">&lt;Unicode 6 digit escape value&gt; ::= &lt;Unicode
      escape character&gt;&lt;plus sign&gt;
      &lt;hexit&gt;&lt;hexit&gt;&lt;hexit&gt;&lt;hexit&gt;&lt;hexit&gt;&lt;hexit&gt;</code>
</p>
<p>
<code class="literal">&lt;Unicode character escape value&gt; ::= &lt;Unicode
      escape character&gt;&lt;Unicode escape character&gt;</code>
</p>
<p>
<code class="literal">&lt;Unicode escape character&gt; ::= a single
      character than a &lt;hexit&gt; (a-f, A-F, 0-9), &lt;plus sign&gt;,
      &lt;quote&gt;, &lt;double quote&gt;, or &lt;white
      space&gt;</code>
</p>
<a name="N120AA" class="indexterm"></a>
<p>
<span class="bold"><strong>character literal</strong></span>
</p>
<p>
<span class="emphasis"><em>character literal</em></span>
</p>
<p>
<code class="literal">&lt;character string literal&gt; ::= [
      &lt;introducer&gt;&lt;character set specification&gt; ] &lt;quote&gt; [
      &lt;character representation&gt;... ] &lt;quote&gt; [ {
      &lt;separator&gt; &lt;quote&gt; [ &lt;character representation&gt;... ]
      &lt;quote&gt; }... ]</code>
</p>
<p>
<code class="literal">&lt;introducer&gt; ::=
      &lt;underscore&gt;</code>
</p>
<p>
<code class="literal">&lt;character representation&gt; ::= &lt;nonquote
      character&gt; | &lt;quote symbol&gt;</code>
</p>
<p>
<code class="literal">&lt;nonquote character&gt; ::= any character apart
      from the quote symbol.</code>
</p>
<p>
<code class="literal">&lt;quote symbol&gt; ::=
      &lt;quote&gt;&lt;quote&gt;</code>
</p>
<p>
<code class="literal">&lt;national character string literal&gt; ::= N
      &lt;quote&gt; [ &lt;character representation&gt;... ] &lt;quote&gt; [ {
      &lt;separator&gt; &lt;quote&gt; [ &lt;character representation&gt;... ]
      &lt;quote&gt; }... ]</code>
</p>
<p>
<code class="literal">&lt;Unicode character string literal&gt; ::= [
      &lt;introducer&gt;&lt;character set specification&gt; ]
      U&lt;ampersand&gt;&lt;quote&gt; [ &lt;Unicode representation&gt;... ]
      &lt;quote&gt; [ { &lt;separator&gt; &lt;quote&gt; [ &lt;Unicode
      representation&gt;... ] &lt;quote&gt; }... ] &lt;Unicode escape
      specifier&gt;</code>
</p>
<p>
<code class="literal">&lt;Unicode representation&gt; ::= &lt;character
      representation&gt; | &lt;Unicode escape value&gt;</code>
</p>
<p>The type of a character literal is CHARACTER. The length of the
      string literal is the character length of the type. If the quote
      character is used in a string, it is represented with two quote
      characters. Long literals can be divided into multiple quoted strings,
      separated with a space or end-of-line character.</p>
<p>Unicode literals start with U&amp; and can contain ordinary
      characters and unicode escapes. A unicode escape begins with the
      backslash ( \ ) character and is followed by four hexadecimal characters
      which specify the character code.</p>
<p>Example of character literals are given below:</p>
<pre class="programlisting"> 'a literal'  ' string seperated'  ' into parts'
 'a string''s literal form with quote character'
 U&amp;'Unicode string with Greek delta \0394 and phi \03a6 letters'
</pre>
<a name="N120D6" class="indexterm"></a>
<p>
<span class="bold"><strong>binary literal</strong></span>
</p>
<p>
<span class="emphasis"><em>binary literal</em></span>
</p>
<p>
<code class="literal">&lt;binary string literal&gt; ::= X &lt;quote&gt; [
      &lt;space&gt;... ] [ { &lt;hexit&gt; [ &lt;space&gt;... ] &lt;hexit&gt;
      [ &lt;space&gt;... ] }... ] &lt;quote&gt; [ { &lt;separator&gt;
      &lt;quote&gt; [ &lt;space&gt;... ] [ { &lt;hexit&gt; [ &lt;space&gt;...
      ] &lt;hexit&gt; [ &lt;space&gt;... ] }... ] &lt;quote&gt; }...
      ]</code>
</p>
<p>
<code class="literal">&lt;hexit&gt; ::= &lt;digit&gt; | A | B | C | D | E |
      F | a | b | c | d | e | f</code>
</p>
<p>The type of a binary literal is BINARY. The octet length of the
      binary literal is the length of the type. Case-insensitive hexadecimal
      characters are used in the binary string. Each pair of characters in the
      literal represents a byte in the binary string. Long literals can be
      divided into multiple quoted strings, separated with a space or
      end-of-line character.</p>
<pre class="programlisting"> X'1abACD34' 'Af'</pre>
<a name="N120EC" class="indexterm"></a>
<p>
<span class="bold"><strong>bit literal</strong></span>
</p>
<p>
<span class="emphasis"><em>bit literal</em></span>
</p>
<p>
<code class="literal">&lt;bit string literal&gt; ::= B &lt;quote&gt; [
      &lt;bit&gt; ... ] &lt;quote&gt; [ { &lt;separator&gt; &lt;quote&gt; [
      &lt;bit&gt;... ] &lt;quote&gt; }... ]</code>
</p>
<p>
<code class="literal">&lt;bit&gt; ::= 0 | 1</code>
</p>
<p>The type of a binary literal is BIT. The bit length of the bit
      literal is the length of the type. Digits 0 and 1 are used to represent
      the bits. Long literals can be divided into multiple quoted strings,
      separated with a space or end-of-line character.</p>
<pre class="programlisting"> B'10001001' '00010'</pre>
<a name="N12102" class="indexterm"></a>
<p>
<span class="bold"><strong>numeric literal</strong></span>
</p>
<p>
<span class="emphasis"><em>numeric literal</em></span>
</p>
<p>
<code class="literal">&lt;signed numeric literal&gt; ::= [ &lt;sign&gt; ]
      &lt;unsigned numeric literal&gt;</code>
</p>
<p>
<code class="literal">&lt;unsigned numeric literal&gt; ::= &lt;exact numeric
      literal&gt; | &lt;approximate numeric literal&gt;</code>
</p>
<p>
<code class="literal">&lt;exact numeric literal&gt; ::= &lt;unsigned
      integer&gt; [ &lt;period&gt; [ &lt;unsigned integer&gt; ] ] |
      &lt;period&gt; &lt;unsigned integer&gt;</code>
</p>
<p>
<code class="literal">&lt;sign&gt; ::= &lt;plus sign&gt; | &lt;minus
      sign&gt;</code>
</p>
<p>
<code class="literal">&lt;approximate numeric literal&gt; ::=
      &lt;mantissa&gt; E &lt;exponent&gt;</code>
</p>
<p>
<code class="literal">&lt;mantissa&gt; ::= &lt;exact numeric
      literal&gt;</code>
</p>
<p>
<code class="literal">&lt;exponent&gt; ::= &lt;signed
      integer&gt;</code>
</p>
<p>
<code class="literal">&lt;signed integer&gt; ::= [ &lt;sign&gt; ]
      &lt;unsigned integer&gt;</code>
</p>
<p>
<code class="literal">&lt;unsigned integer&gt; ::=
      &lt;digit&gt;...</code>
</p>
<p>The type of an exact numeric literal without a decimal point is
      INTEGER, BIGINT, or DECIMAL, depending on the value of the literal (the
      smallest type that can represent the value is the type).</p>
<p>The type of an exact numeric literal with a decimal point is
      DECIMAL. The precision of a decimal literal is the total number of
      digits of the literal. The scale of the literal is the total number of
      digits to the right of the decimal point.</p>
<p>The type of an approximate numeric literal is DOUBLE. An
      approximate numeric literal always includes the mantissa and exponent,
      separated by E.</p>
<pre class="programlisting"> 12
 34.35
 +12E-2
</pre>
<a name="N12131" class="indexterm"></a>
<p>
<span class="bold"><strong>boolean literal</strong></span>
</p>
<p>
<span class="emphasis"><em>boolean literal</em></span>
</p>
<p>
<code class="literal">&lt;boolean literal&gt; ::= TRUE | FALSE |
      UNKNOWN</code>
</p>
<p>The boolean literal is one of the specified keywords.</p>
<a name="N12142" class="indexterm"></a>
<p>
<span class="bold"><strong>datetime and interval
      literal</strong></span>
</p>
<p>
<span class="emphasis"><em>datetime and interval literal</em></span>
</p>
<p>
<code class="literal">&lt;datetime literal&gt; ::= &lt;date literal&gt; |
      &lt;time literal&gt; | &lt;timestamp literal&gt;</code>
</p>
<p>
<code class="literal">&lt;date literal&gt; ::= DATE &lt;date
      string&gt;</code>
</p>
<p>
<code class="literal">&lt;time literal&gt; ::= TIME &lt;time
      string&gt;</code>
</p>
<p>
<code class="literal">&lt;timestamp literal&gt; ::= TIMESTAMP &lt;timestamp
      string&gt;</code>
</p>
<p>
<code class="literal">&lt;date string&gt; ::= &lt;quote&gt; &lt;unquoted
      date string&gt; &lt;quote&gt;</code>
</p>
<p>
<code class="literal">&lt;time string&gt; ::= &lt;quote&gt; &lt;unquoted
      time string&gt; &lt;quote&gt;</code>
</p>
<p>
<code class="literal">&lt;timestamp string&gt; ::= &lt;quote&gt;
      &lt;unquoted timestamp string&gt; &lt;quote&gt;</code>
</p>
<p>
<code class="literal">&lt;time zone interval&gt; ::= &lt;sign&gt; &lt;hours
      value&gt; &lt;colon&gt; &lt;minutes value&gt;</code>
</p>
<p>
<code class="literal">&lt;date value&gt; ::= &lt;years value&gt; &lt;minus
      sign&gt; &lt;months value&gt; &lt;minus sign&gt; &lt;days
      value&gt;</code>
</p>
<p>
<code class="literal">&lt;time value&gt; ::= &lt;hours value&gt;
      &lt;colon&gt; &lt;minutes value&gt; &lt;colon&gt; &lt;seconds
      value&gt;</code>
</p>
<p>
<code class="literal">&lt;interval literal&gt; ::= INTERVAL [ &lt;sign&gt; ]
      &lt;interval string&gt; &lt;interval qualifier&gt;</code>
</p>
<p>
<code class="literal">&lt;interval string&gt; ::= &lt;quote&gt; &lt;unquoted
      interval string&gt; &lt;quote&gt;</code>
</p>
<p>
<code class="literal">&lt;unquoted date string&gt; ::= &lt;date
      value&gt;</code>
</p>
<p>
<code class="literal">&lt;unquoted time string&gt; ::= &lt;time value&gt; [
      &lt;time zone interval&gt; ]</code>
</p>
<p>
<code class="literal">&lt;unquoted timestamp string&gt; ::= &lt;unquoted
      date string&gt; &lt;space&gt; &lt;unquoted time
      string&gt;</code>
</p>
<p>
<code class="literal">&lt;unquoted interval string&gt; ::= [ &lt;sign&gt; ]
      { &lt;year-month literal&gt; | &lt;day-time literal&gt;
      }</code>
</p>
<p>
<code class="literal">&lt;year-month literal&gt; ::= &lt;years value&gt; [
      &lt;minus sign&gt; &lt;months value&gt; ] | &lt;months
      value&gt;</code>
</p>
<p>
<code class="literal">&lt;day-time literal&gt; ::= &lt;day-time interval&gt;
      | &lt;time interval&gt;</code>
</p>
<p>
<code class="literal">&lt;day-time interval&gt; ::= &lt;days value&gt; [
      &lt;space&gt; &lt;hours value&gt; [ &lt;colon&gt; &lt;minutes value&gt;
      [ &lt;colon&gt; &lt;seconds value&gt; ] ] ]</code>
</p>
<p>
<code class="literal">&lt;time interval&gt; ::= &lt;hours value&gt; [
      &lt;colon&gt; &lt;minutes value&gt; [ &lt;colon&gt; &lt;seconds
      value&gt; ] ] | &lt;minutes value&gt; [ &lt;colon&gt; &lt;seconds
      value&gt; ] | &lt;seconds value&gt;</code>
</p>
<p>
<code class="literal">&lt;years value&gt; ::= &lt;datetime
      value&gt;</code>
</p>
<p>
<code class="literal">&lt;months value&gt; ::= &lt;datetime
      value&gt;</code>
</p>
<p>
<code class="literal">&lt;days value&gt; ::= &lt;datetime
      value&gt;</code>
</p>
<p>
<code class="literal">&lt;hours value&gt; ::= &lt;datetime
      value&gt;</code>
</p>
<p>
<code class="literal">&lt;minutes value&gt; ::= &lt;datetime
      value&gt;</code>
</p>
<p>
<code class="literal">&lt;seconds value&gt; ::= &lt;seconds integer
      value&gt; [ &lt;period&gt; [ &lt;seconds fraction&gt; ]
      ]</code>
</p>
<p>
<code class="literal">&lt;seconds integer value&gt; ::= &lt;unsigned
      integer&gt;</code>
</p>
<p>
<code class="literal">&lt;seconds fraction&gt; ::= &lt;unsigned
      integer&gt;</code>
</p>
<p>
<code class="literal">&lt;datetime value&gt; ::= &lt;unsigned
      integer&gt;</code>
</p>
<p>The type of a datetime or interval type is specified in the
      literal. The fractional second precision is the number of digits in the
      fractional part of the literal. Details are described in the <a class="link" href="#sqlgeneral-chapt" title="Chapter&nbsp;2.&nbsp;SQL Language">SQL Language</a>
      chapter</p>
<pre class="programlisting"> DATE '2008-08-08'
 TIME '20:08:08'
 TIMESTAMP '2008-08-08 20:08:08.235'

 INTERVAL '10' DAY
 INTERVAL -'08:08' MINUTE TO SECOND
</pre>
</div>
<div class="section" title="References, etc.">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_sql_references"></a>References, etc.</h3>
</div>
</div>
</div>
<p>References are identifier chains, which can be a single
      identifiers or identifiers chains composed of single identifiers chained
      together with the period symbol.</p>
<a name="N121B3" class="indexterm"></a>
<p>
<span class="bold"><strong>identifier chain</strong></span>
</p>
<p>
<span class="emphasis"><em>identifier chain</em></span>
</p>
<p>
<code class="literal">&lt;identifier chain&gt; ::= &lt;identifier&gt; [ {
      &lt;period&gt; &lt;identifier&gt; }... ]</code>
</p>
<p>
<code class="literal">&lt;basic identifier chain&gt; ::= &lt;identifier
      chain&gt;</code>
</p>
<p>A period-separated chain of identifiers. The identifiers in an
      identifier chain can refer to database objects in a hierarchy. The
      possible hierarchies are as follows. In each hierarchy, elements from
      the start or the end can be missing, but the order of elements cannot be
      changed.</p>
<p>catalog, schema, database object</p>
<p>catalog, schema, table, column</p>
<p>correlation name, column</p>
<p>Examples of identifier chain are given below:</p>
<pre class="programlisting"> SELECT MYCAT.MYSCHEMA.MYTABLE.MYCOL FROM MYCAT.MYSCHEMA.MYTABLE
 DROP TABLE MYCAT.MYSCHEMA.MYTABLE CASCADE
 ALTER SEQUENCE MYCAT.MYSCHEMA.MYSEQUENCE RESTART WITH 100
</pre>
<a name="N121D1" class="indexterm"></a>
<p>
<span class="bold"><strong>column reference</strong></span>
</p>
<p>
<span class="emphasis"><em>column reference</em></span>
</p>
<p>
<code class="literal">&lt;column reference&gt; ::= &lt;basic identifier
      chain&gt; | MODULE &lt;period&gt; &lt;qualified identifier&gt;
      &lt;period&gt; &lt;column name&gt;</code>
</p>
<p>Reference a column or a routine variable.</p>
<a name="N121E2" class="indexterm"></a>
<p>
<span class="bold"><strong>SQL parameter
      reference</strong></span>
</p>
<p>
<span class="emphasis"><em>SQL parameter reference</em></span>
</p>
<p>
<code class="literal">&lt;SQL parameter reference&gt; ::= &lt;basic
      identifier chain&gt;</code>
</p>
<p>Reference an SQL routine parameter.</p>
<a name="N121F3" class="indexterm"></a>
<p>
<span class="bold"><strong>contextually typed value
      specification</strong></span>
</p>
<p>
<span class="emphasis"><em>contextually typed value
      specification</em></span>
</p>
<p>
<code class="literal">&lt;contextually typed value specification&gt; ::=
      &lt;null specification&gt; | &lt;default
      specification&gt;</code>
</p>
<p>
<code class="literal">&lt;null specification&gt; ::=
      NULL</code>
</p>
<p>
<code class="literal">&lt;default specification&gt; ::=
      DEFAULT</code>
</p>
<p>Specify a value whose data type or value is inferred from its
      context.</p>
<p>DEFAULT is used for assignments to table columns that have a
      default value, or to table columns that are generated either as an
      IDENTITY value or as an expression. </p>
<p>NULL can be used only in a context where the type of the value
      is known. For example, a NULL can be assigned to a column of the table
      in an INSERT or UPDATE statement, because the type of the column is
      known. But if NULL is used in a SELECT list, it must be used in a CAST
      statement.</p>
</div>
<div class="section" title="Value Expression">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_value_expression"></a>Value Expression</h3>
</div>
</div>
</div>
<p>Value expression is a general name for all expressions that return
      a value. Different types of expressions are allowed in different
      contexts.</p>
<a name="N12214" class="indexterm"></a>
<p>
<span class="bold"><strong>value expression
      primary</strong></span>
</p>
<p>
<span class="emphasis"><em>value expression primary</em></span>
</p>
<p>
<code class="literal">&lt;value expression primary&gt; ::= &lt;parenthesized
      value expression&gt; | &lt;nonparenthesized value expression
      primary&gt;</code>
</p>
<p>
<code class="literal">&lt;parenthesized value expression&gt; ::= &lt;left
      paren&gt; &lt;value expression&gt; &lt;right
      paren&gt;</code>
</p>
<p>
<code class="literal">&lt;nonparenthesized value expression primary&gt; ::=
      &lt;unsigned value specification&gt; | &lt;column reference&gt; |
      &lt;set function specification&gt; | &lt;scalar subquery&gt; | &lt;case
      expression&gt; | &lt;cast specification&gt; | &lt;next value
      expression&gt; | &lt;current value expression&gt; | &lt;routine
      invocation&gt;</code>
</p>
<p>Specify a value that is syntactically self-delimited.</p>
<a name="N1222B" class="indexterm"></a>
<p>
<span class="bold"><strong>value specification</strong></span>
</p>
<p>
<span class="emphasis"><em>value specification</em></span>
</p>
<p>
<code class="literal">&lt;value specification&gt; ::= &lt;literal&gt; |
      &lt;general value specification&gt;</code>
</p>
<p>
<code class="literal">&lt;unsigned value specification&gt; ::= &lt;unsigned
      literal&gt; | &lt;general value specification&gt;</code>
</p>
<p>
<code class="literal">&lt;target specification&gt; ::= &lt;host parameter
      specification&gt; | &lt;SQL parameter reference&gt; | &lt;column
      reference&gt; | &lt;dynamic parameter
      specification&gt;</code>
</p>
<p>
<code class="literal">&lt;simple target specification&gt; ::= &lt;host
      parameter specification&gt; | &lt;SQL parameter reference&gt; |
      &lt;column reference&gt; | &lt;embedded variable
      name&gt;</code>
</p>
<p>
<code class="literal">&lt;host parameter specification&gt; ::= &lt;host
      parameter name&gt; [ &lt;indicator parameter&gt; ]</code>
</p>
<p>
<code class="literal">&lt;dynamic parameter specification&gt; ::=
      &lt;question mark&gt;</code>
</p>
<p>Specify one or more values, host parameters, SQL parameters,
      dynamic parameters, or host variables.</p>
<a name="N1224B" class="indexterm"></a>
<p>
<span class="bold"><strong>row value expression</strong></span>
</p>
<p>
<span class="emphasis"><em>row value expression</em></span>
</p>
<p>
<code class="literal">&lt;row value expression&gt; ::= &lt;row value special
      case&gt; | &lt;explicit row value constructor&gt; </code>
</p>
<p>
<code class="literal">&lt;row value predicand&gt; ::= &lt;row value special
      case&gt; | &lt;row value constructor predicand&gt;</code>
</p>
<p>
<code class="literal">&lt;row value special case&gt; ::=
      &lt;nonparenthesized value expression primary&gt;</code>
</p>
<p>
<code class="literal">&lt;explicit row value constructor&gt; ::= &lt;left
      paren&gt; &lt;row value constructor element&gt; &lt;comma&gt; &lt;row
      value constructor element list&gt; &lt;right paren&gt;
      |</code>
</p>
<p>
<code class="literal"> ROW &lt;left paren&gt; &lt;row value constructor
      element list&gt; &lt;right paren&gt; | &lt;row
      subquery&gt;</code>
</p>
<p>Specify a row consisting of one or more elements. A comma
      separated list of expressions, enclosed in brackets, with the optional
      keyword ROW. In SQL, a row containing a single element can often be used
      where a single value is expected.</p>
<a name="N12268" class="indexterm"></a>
<p>
<span class="bold"><strong>set function
      specification</strong></span>
</p>
<p>
<span class="emphasis"><em>set function specification</em></span>
</p>
<p>
<code class="literal">&lt;set function specification&gt; ::= &lt;aggregate
      function&gt; | &lt;grouping operation&gt;</code>
</p>
<p>
<code class="literal">&lt;grouping operation&gt; ::= GROUPING &lt;left
      paren&gt; &lt;column reference&gt; [ { &lt;comma&gt; &lt;column
      reference&gt; }... ] &lt;right paren&gt;</code>
</p>
<p>Specify a value derived by the application of a function to an
      argument. HyperSQL does not yet support <code class="literal">&lt;grouping
      operation&gt;</code> .</p>
<a name="N1227F" class="indexterm"></a>
<p>
<span class="bold"><strong>COALESCE</strong></span>
</p>
<p>
<span class="emphasis"><em>coalesce expression</em></span>
</p>
<p>
<code class="literal">&lt;coalesce expression&gt; := COALESCE &lt;left
      paren&gt; &lt;value expression&gt; { &lt;comma&gt; &lt;value
      expression&gt; }... &lt;right paren&gt;</code>
</p>
<p>Replace null values with another value. The coalesce expression
      has two or more instances of &lt;value expression&gt;. If the first
      &lt;value expression&gt; evaluates to a non-null value, it is returned
      as the result of the coalesce expression. If it is null, the next
      <code class="literal">&lt;value expression&gt;</code> is evaluated and if it
      evaluates to a non-non value, it is returned, and so on.</p>
<p>The type of the return value of a COALESCE expression is the
      aggregate type of the types of all the <code class="literal">&lt;value
      expression&gt;</code> instances. Therefore, any value returned is
      implicitly cast to this type. HyperSQL also features built-in functions
      with similar functionality.</p>
<a name="N12298" class="indexterm"></a>
<p>
<span class="bold"><strong>NULLIF</strong></span>
</p>
<p>
<span class="emphasis"><em>nullif expression</em></span>
</p>
<p>
<code class="literal">&lt;nullif expression&gt; := NULLIF &lt;left paren&gt;
      &lt;value expression&gt; &lt;comma&gt; &lt;value expression&gt;
      &lt;right paren&gt;</code>
</p>
<p>Return NULL if two values are equal. If the result of the first
      <code class="literal">&lt;value expression&gt;</code> is not equal to the result
      of the second, then it is returned, otherwise NULL is returned. The type
      of the return value is the type of the first <code class="literal">&lt;value
      expression&gt;</code>.</p>
<pre class="programlisting"> SELECT i, NULLIF(n, 'not defined') FROM t</pre>
<a name="N122B1" class="indexterm"></a>
<p>
<span class="bold"><strong>CASE</strong></span>
</p>
<p>
<span class="emphasis"><em>case specification</em></span>
</p>
<p>
<code class="literal">&lt;case specification&gt; ::= &lt;simple case&gt; |
      &lt;searched case&gt;</code>
</p>
<p>
<code class="literal">&lt;simple case&gt; ::= CASE &lt;case operand&gt;
      &lt;simple when clause&gt;... [ &lt;else clause&gt; ]
      END</code>
</p>
<p>
<code class="literal">&lt;searched case&gt; ::= CASE &lt;searched when
      clause&gt;... [ &lt;else clause&gt; ] END</code>
</p>
<p>
<code class="literal">&lt;simple when clause&gt; ::= WHEN &lt;when operand
      list&gt; THEN &lt;result&gt;</code>
</p>
<p>
<code class="literal">&lt;searched when clause&gt; ::= WHEN &lt;search
      condition&gt; THEN &lt;result&gt;</code>
</p>
<p>
<code class="literal">&lt;else clause&gt; ::= ELSE
      &lt;result&gt;</code>
</p>
<p>
<code class="literal">&lt;case operand&gt; ::= &lt;row value predicand&gt; |
      &lt;overlaps predicate part 1&gt;</code>
</p>
<p>
<code class="literal">&lt;when operand list&gt; ::= &lt;when operand&gt; [ {
      &lt;comma&gt; &lt;when operand&gt; }... ]</code>
</p>
<p>
<code class="literal">&lt;when operand&gt; ::= &lt;row value predicand&gt; |
      &lt;comparison predicate part 2&gt; | &lt;between predicate part 2&gt; |
      &lt;in predicate part 2&gt; | &lt;character like predicate part 2&gt; |
      &lt;octet like predicate part 2&gt; | &lt;similar predicate part 2&gt; |
      &lt;regex like predicate part 2&gt; | &lt;null predicate part 2&gt; |
      &lt;quantified comparison predicate part 2&gt; | &lt;match predicate
      part 2&gt; | &lt;overlaps predicate part 2&gt; | &lt;distinct predicate
      part 2&gt;</code>
</p>
<p>
<code class="literal">&lt;result&gt; ::= &lt;result expression&gt; |
      NULL</code>
</p>
<p>
<code class="literal">&lt;result expression&gt; ::= &lt;value
      expression&gt;</code>
</p>
<p>Specify a conditional value. The result of a case expression is
      always a value. All the values introduced with THEN must be of the same
      type.</p>
<p>Some simple examples of the CASE expression are given below.
      The first two examples return 'Britain', 'Germany', or 'Other country'
      depending on the value of dialcode. The third example uses IN and
      smaller-than predicates.</p>
<pre class="programlisting"> CASE dialcode WHEN 44 THEN 'Britain' WHEN 49 THEN 'Germany' ELSE 'Other country' END
 CASE WHEN dialcode=44 THEN 'Britain' WHEN dialcode=49 THEN 'Germany' WHEN dialcode &lt; 0 THEN 'bad dial code' ELSE 'Other country' END
 CASE dialcode WHEN IN (44, 49,30) THEN 'Europe' WHEN IN (86,91,91) THEN 'Asia' WHEN &lt; 0 THEN 'bad dial code' ELSE 'Other continent' END
</pre>
<p>The case statement can be far more complex and involve several
      conditions.</p>
<a name="N122E6" class="indexterm"></a>
<p>
<span class="bold"><strong>CAST</strong></span>
</p>
<p>
<span class="emphasis"><em>cast specification</em></span>
</p>
<p>
<code class="literal">&lt;cast specification&gt; ::= CAST &lt;left paren&gt;
      &lt;cast operand&gt; AS &lt;cast target&gt; &lt;right
      paren&gt;</code>
</p>
<p>
<code class="literal">&lt;cast operand&gt; ::= &lt;value expression&gt; |
      &lt;implicitly typed value specification&gt;</code>
</p>
<p>
<code class="literal">&lt;cast target&gt; ::= &lt;domain name&gt; | &lt;data
      type&gt;</code>
</p>
<p>Specify a data conversion. Data conversion takes place
      automatically among variants of a general type. For example numeric
      values are freely converted from one type to another in
      expressions.</p>
<p>Explicit type conversion is necessary in two cases. One case is
      to determine the type of a NULL value. The other case is to force
      conversion for special purposes. Values of data types can be cast to a
      character type. The exception is BINARY and OTHER types. The result of
      the cast is the literal expression of the value. Conversely, a value of
      a character type can be converted to another type if the character value
      is a literal representation of the value in the target type. Special
      conversions are possible between numeric and interval types, which are
      described in the section covering interval types.</p>
<p>The examples below show examples of cast with their
      result:</p>
<pre class="programlisting"> CAST (NULL AS TIMESTAMP)
 CAST ('   199  ' AS INTEGER) = 199
 CAST ('tRue ' AS BOOLEAN) = TRUE
 CAST (INTERVAL '2' DAY AS INTEGER) = 2
 CAST ('1992-04-21' AS DATE) = DATE '1992-04-21'
</pre>
<a name="N12303" class="indexterm"></a>
<p>
<span class="bold"><strong>NEXT VALUE FOR</strong></span>
</p>
<p>
<span class="emphasis"><em>next value expression</em></span>
</p>
<p>
<code class="literal">&lt;next value expression&gt; ::= NEXT VALUE FOR
      &lt;sequence generator name&gt;</code>
</p>
<p>Return the next value of a sequence generator. This expression
      can be used as a select list element in queries, or in assignments to
      table columns in data change statements. If the expression is used more
      than once in a single row that is being evaluated, the same value is
      returned for each invocation. After evaluation of the particular row is
      complete, the sequence generator will return a different value from the
      old value. The new value is generated by the sequence generator by
      adding the increment to the last value it generated. In the example
      below the expression is used in an insert statement:</p>
<pre class="programlisting">INSERT INTO MYTABLE(COL1, COL2) VALUES 2, NEXT VALUE FOR MYSEQUENCE
</pre>
<a name="N12316" class="indexterm"></a>
<p>
<span class="bold"><strong>CURRENT VALUE FOR</strong></span>
</p>
<p>
<span class="emphasis"><em>current value expression</em></span>
</p>
<p>
<code class="literal">&lt;current value expression&gt; ::= CURRENT VALUE FOR
      &lt;sequence generator name&gt;</code>
</p>
<p>Return the latest value that was returned by the NEXT VALUE FOR
      expression for a sequence generator. In the example below, the value
      that was generated by the sequence for the first insert, is reused for
      the second insert:</p>
<pre class="programlisting"> INSERT INTO MYTABLE(COL1, COL2) VALUES 2, NEXT VALUE FOR MYSEQUENCE;
 INSERT INTO CHILDTABLE(COL1, COL2) VALUES 10, CURRENT VALUE FOR MYSEQUENCE;
</pre>
<a name="N12329" class="indexterm"></a>
<p>
<span class="bold"><strong>value expression</strong></span>
</p>
<p>
<span class="emphasis"><em>value expression</em></span>
</p>
<p>
<code class="literal">&lt;value expression&gt; ::= &lt;numeric value
      expression&gt; | &lt;string value expression&gt; | &lt;datetime value
      expression&gt; | &lt;interval value expression&gt; | &lt;boolean value
      expression&gt; | &lt;row value expression&gt;</code>
</p>
<p>An expression that returns a value. The value can be a single
      value, or a row consisting more than one value.</p>
<a name="N1233A" class="indexterm"></a>
<p>
<span class="bold"><strong>numeric value
      expression</strong></span>
</p>
<p>
<span class="emphasis"><em>numeric value expression</em></span>
</p>
<p>
<code class="literal">&lt;numeric value expression&gt; ::= &lt;term&gt; |
      &lt;numeric value expression&gt; &lt;plus sign&gt; &lt;term&gt; |
      &lt;numeric value expression&gt; &lt;minus sign&gt;
      &lt;term&gt;</code>
</p>
<p>
<code class="literal">&lt;term&gt; ::= &lt;factor&gt; | &lt;term&gt;
      &lt;asterisk&gt; &lt;factor&gt; | &lt;term&gt; &lt;solidus&gt;
      &lt;factor&gt;</code>
</p>
<p>
<code class="literal">&lt;factor&gt; ::= [ &lt;sign&gt; ] &lt;numeric
      primary&gt;</code>
</p>
<p>
<code class="literal">&lt;numeric primary&gt; ::= &lt;value expression
      primary&gt; | &lt;numeric value function&gt;</code>
</p>
<p>Specify a numeric value. The BNF indicates that
      <code class="literal">&lt;asterisk&gt;</code> and
      <code class="literal">&lt;solidus&gt;</code> (the operators for multiplication and
      division) have precedence over <code class="literal">&lt;minus sign&gt;</code> and
      <code class="literal">&lt;plus sign&gt;</code>.</p>
<a name="N12360" class="indexterm"></a>
<p>
<span class="bold"><strong>numeric value
      function</strong></span>
</p>
<p>
<span class="emphasis"><em>numeric value function</em></span>
</p>
<p>
<code class="literal">&lt;numeric value function&gt; ::= &lt;position
      expression&gt; | &lt;extract expression&gt; | &lt;length expression&gt;
      ...</code>
</p>
<p>Specify a function yielding a value of type numeric. The
      supported numeric value functions are listed and described in the <a class="link" href="#builtinfunctions-chapt" title="Chapter&nbsp;10.&nbsp;Built In Functions">Built In Functions</a> chapter.</p>
<a name="N12375" class="indexterm"></a>
<p>
<span class="bold"><strong>string value
      expression</strong></span>
</p>
<p>
<span class="emphasis"><em>string value expression</em></span>
</p>
<p>
<code class="literal">&lt;string value expression&gt; ::= &lt;string
      concatenation&gt; | &lt;string factor&gt;</code>
</p>
<p>
<code class="literal">&lt;string factor&gt; ::= &lt;value expression
      primary&gt; | &lt;string value function&gt;</code>
</p>
<p>
<code class="literal">&lt;string concatenation&gt; ::= &lt;string value
      expression&gt; &lt;concatenation operator&gt; &lt;string
      factor&gt;</code>
</p>
<p>
<code class="literal">&lt;concatenation operator&gt; ::=
      ||</code>
</p>
<p>Specify a character string value, a binary string value, or a
      bit string value. The BNF indicates that a string value expression can
      be formed by concatenation of two or more <code class="literal">&lt;value expression
      primary&gt;</code>. The types of the <code class="literal">&lt;value expression
      primary&gt;</code> elements must be compatible, that is, all must be
      string, or binary or bit string values.</p>
<a name="N12395" class="indexterm"></a>
<p>
<span class="bold"><strong>character value
      function</strong></span>
</p>
<p>
<span class="emphasis"><em>string value function</em></span>
</p>
<p>
<code class="literal">&lt;string value function&gt; ::=
      ...</code>
</p>
<p>Specify a function that returns a character string or binary
      string. The supported character value functions are listed and described
      in the <a class="link" href="#builtinfunctions-chapt" title="Chapter&nbsp;10.&nbsp;Built In Functions">Built In Functions</a> chapter.</p>
<a name="N123AA" class="indexterm"></a>
<p>
<span class="bold"><strong>datetime value
      expression</strong></span>
</p>
<p>
<span class="emphasis"><em>datetime value expression</em></span>
</p>
<p>
<code class="literal">&lt;datetime value expression&gt; ::= &lt;datetime
      term&gt; | &lt;interval value expression&gt; &lt;plus sign&gt;
      &lt;datetime term&gt; | &lt;datetime value expression&gt; &lt;plus
      sign&gt; &lt;interval term&gt; | &lt;datetime value expression&gt;
      &lt;minus sign&gt; &lt;interval term&gt;</code>
</p>
<p>
<code class="literal">&lt;datetime term&gt; ::= &lt;datetime
      factor&gt;</code>
</p>
<p>
<code class="literal">&lt;datetime factor&gt; ::= &lt;datetime primary&gt; [
      &lt;time zone&gt; ]</code>
</p>
<p>
<code class="literal">&lt;datetime primary&gt; ::= &lt;value expression
      primary&gt; | &lt;datetime value function&gt;</code>
</p>
<p>
<code class="literal">&lt;time zone&gt; ::= AT &lt;time zone
      specifier&gt;</code>
</p>
<p>
<code class="literal">&lt;time zone specifier&gt; ::= LOCAL | TIME ZONE
      &lt;interval primary&gt;</code>
</p>
<p>Specify a datetime value. Details are described in the <a class="link" href="#sqlgeneral-chapt" title="Chapter&nbsp;2.&nbsp;SQL Language">SQL Language</a>
      chapter.</p>
<a name="N123CE" class="indexterm"></a>
<p>
<span class="bold"><strong>datetime value
      function</strong></span>
</p>
<p>
<span class="emphasis"><em>datetime value function</em></span>
</p>
<p>
<code class="literal">&lt;datetime value function&gt; ::=
      ...</code>
</p>
<p>Specify a function that returns a datetime value. The supported
      datetime value functions are listed and described in the <a class="link" href="#builtinfunctions-chapt" title="Chapter&nbsp;10.&nbsp;Built In Functions">Built In Functions</a> chapter.</p>
<a name="N123E4" class="indexterm"></a>
<p>
<span class="bold"><strong>interval term</strong></span>
</p>
<p>
<span class="emphasis"><em>interval value expression</em></span>
</p>
<p>
<code class="literal">&lt;interval value expression&gt; ::= &lt;interval
      term&gt; | &lt;interval value expression 1&gt; &lt;plus sign&gt;
      &lt;interval term 1&gt; | &lt;interval value expression 1&gt; &lt;minus
      sign&gt; &lt;interval term 1&gt; | &lt;left paren&gt; &lt;datetime value
      expression&gt; &lt;minus sign&gt; &lt;datetime term&gt; &lt;right
      paren&gt; &lt;interval qualifier&gt;</code>
</p>
<p>
<code class="literal">&lt;interval term&gt; ::= &lt;interval factor&gt; |
      &lt;interval term 2&gt; &lt;asterisk&gt; &lt;factor&gt; | &lt;interval
      term 2&gt; &lt;solidus&gt; &lt;factor&gt; | &lt;term&gt;
      &lt;asterisk&gt; &lt;interval factor&gt;</code>
</p>
<p>
<code class="literal">&lt;interval factor&gt; ::= [ &lt;sign&gt; ]
      &lt;interval primary&gt;</code>
</p>
<p>
<code class="literal">&lt;interval primary&gt; ::= &lt;value expression
      primary&gt; [ &lt;interval qualifier&gt; ] | &lt;interval value
      function&gt;</code>
</p>
<p>
<code class="literal">&lt;interval value expression 1&gt; ::= &lt;interval
      value expression&gt;</code>
</p>
<p>
<code class="literal">&lt;interval term 1&gt; ::= &lt;interval
      term&gt;</code>
</p>
<p>
<code class="literal">&lt;interval term 2&gt; ::= &lt;interval
      term&gt;</code>
</p>
<p>Specify an interval value. Details are described in the <a class="link" href="#sqlgeneral-chapt" title="Chapter&nbsp;2.&nbsp;SQL Language">SQL Language</a>
      chapter.</p>
<a name="N1240B" class="indexterm"></a>
<p>
<span class="bold"><strong>interval absolute value
      function</strong></span>
</p>
<p>
<span class="emphasis"><em>interval value function</em></span>
</p>
<p>
<code class="literal">&lt;interval value function&gt; ::= &lt;interval
      absolute value function&gt;</code>
</p>
<p>
<code class="literal">&lt;interval absolute value function&gt; ::= ABS
      &lt;left paren&gt; &lt;interval value expression&gt; &lt;right
      paren&gt;</code>
</p>
<p>Specify a function that returns the absolute value of an
      interval. If the interval is negative, it is negated, otherwise the
      original value is returned.</p>
<a name="N1241F" class="indexterm"></a>
<p>
<span class="bold"><strong>boolean value
      expression</strong></span>
</p>
<p>
<span class="emphasis"><em>boolean value expression</em></span>
</p>
<p>
<code class="literal">&lt;boolean value expression&gt; ::= &lt;boolean
      term&gt; | &lt;boolean value expression&gt; OR &lt;boolean
      term&gt;</code>
</p>
<p>
<code class="literal">&lt;boolean term&gt; ::= &lt;boolean factor&gt; |
      &lt;boolean term&gt; AND &lt;boolean factor&gt;</code>
</p>
<p>
<code class="literal">&lt;boolean factor&gt; ::= [ NOT ] &lt;boolean
      test&gt;</code>
</p>
<p>
<code class="literal">&lt;boolean test&gt; ::= &lt;boolean primary&gt; [ IS
      [ NOT ] &lt;truth value&gt; ]</code>
</p>
<p>
<code class="literal">&lt;truth value&gt; ::= TRUE | FALSE |
      UNKNOWN</code>
</p>
<p>
<code class="literal">&lt;boolean primary&gt; ::= &lt;predicate&gt; |
      &lt;boolean predicand&gt;</code>
</p>
<p>
<code class="literal">&lt;boolean predicand&gt; ::= &lt;parenthesized
      boolean value expression&gt; | &lt;nonparenthesized value expression
      primary&gt;</code>
</p>
<p>
<code class="literal">&lt;parenthesized boolean value expression&gt; ::=
      &lt;left paren&gt; &lt;boolean value expression&gt; &lt;right
      paren&gt;</code>
</p>
<p>Specify a boolean value.</p>
</div>
<div class="section" title="Predicates">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_sql_predicates"></a>Predicates</h3>
</div>
</div>
</div>
<p>Predicates are conditions with two sides and evaluate to a
      boolean value. The left side of the predicate, the <code class="literal">&lt;row
      value predicand&gt;</code>, is the common element of all predicates.
      This element is a generalisation of both <code class="literal">&lt;value
      expression&gt;</code>, which is a scalar, and of
      <code class="literal">&lt;explicit row value constructor&gt;</code>, which is a
      row. The two sides of a predicate can be split in CASE statements where
      the <code class="literal">&lt;row value predicand&gt;</code> is part of multiple
      predicates.</p>
<p>The number of fields in all <code class="literal">&lt;row value
      predicand&gt;</code> used in predicates must be the same and the
      types of the fields in the same position must be compatible for
      comparison. If either of these conditions does not hold, an exception is
      raised. The number of fields in a row is called the
      <em class="glossterm">degree</em>.</p>
<p>In many types of predicates (but not all of them), if the
      <code class="literal">&lt;row value predicand&gt;</code> evaluates to NULL, the
      result of the predicate is UNKNOWN. If the <code class="literal">&lt;row value
      predicand&gt;</code> has more than one element, and one or more of
      the fields evaluate to NULL, the result depends on the particular
      predicate.</p>
<a name="N12467" class="indexterm"></a>
<p>
<span class="bold"><strong>comparison predicand</strong></span>
</p>
<p>
<span class="emphasis"><em>comparison predicate</em></span>
</p>
<p>
<code class="literal">&lt;comparison predicate&gt; ::= &lt;row value
      predicand&gt; &lt;comp op&gt; &lt;row value
      predicand&gt;</code>
</p>
<p>
<code class="literal">&lt;comp op&gt; ::= &lt;equals operator&gt; | &lt;not
      equals operator&gt; | &lt;less than operator&gt; | &lt;greater than
      operator&gt; | &lt;less than or equals operator&gt; | &lt;greater than
      or equals operator&gt;</code>
</p>
<p>Specify a comparison of two row values. If either
      <code class="literal">&lt;row value predicand&gt;</code> evaluates to NULL, the
      result of <code class="literal">&lt;comparison predicate&gt;</code> is UNKNOWN.
      Otherwise, the result is TRUE, FALSE or UNKNOWN.</p>
<p>If the <em class="glossterm">degree</em> of <code class="literal">&lt;row value
      predicand&gt;</code> is larger than one, comparison is performed
      between each field and the corresponding field in the other
      <code class="literal">&lt;row value predicand&gt;</code> from left to right, one
      by one.</p>
<p>When comparing two elements, if either field is NULL then the
      result is UNKNOWN.</p>
<p>For <code class="literal">&lt;equals operator&gt;</code>, if the result
      of comparison is TRUE for all field, the result of the predicate is
      TRUE. If the result of comparison is FALSE for one field, the result of
      predicate is FALSE. Otherwise the result is UNKNOWN.</p>
<p>The <code class="literal">&lt;not equals operator&gt;</code> is
      translated to <code class="literal">NOT (&lt;row value predicand&gt; = &lt;row value
      predicand&gt;)</code>.</p>
<p>The <code class="literal">&lt;less than or equals operator&gt;</code> is
      translated to <code class="literal">(&lt;row value predicand&gt; = &lt;row value
      predicand&gt;) OR (&lt;row value predicand&gt; &lt; &lt;row value
      predicand&gt;)</code>. The <code class="literal">&lt;greater than or equals
      operator&gt;</code> is translated similarly.</p>
<p>For the <code class="literal">&lt;less than operator&gt;</code> and
      <code class="literal">&lt;greater than operator&gt;</code>, if two fields at a
      given position are equal, then comparison continues to the next field.
      Otherwise, the result of the last performed comparison is returned as
      the result of the predicate. This means that if the first field is NULL,
      the result is always UNKNOWN.</p>
<p>The logic that governs NULL values and UNKNOWN result is as
      follows: Suppose the NULL values were substituted by arbitrary real
      values. If substitution cannot change the result of the predicate, then
      the result is TRUE or FALSE, based on the existing non-NULL values,
      otherwise the result of the predicate is UNKNOWN.</p>
<p>The examples of comparison given below use literals, but the
      literals actually represent the result of evaluation of some
      expression.</p>
<pre class="programlisting"> ((1, 2, 3, 4) = (1, 2, 3, 4)) IS TRUE
 ((1, 2, 3, 4) = (1, 2, 3, 5)) IS FALSE
 ((1, 2, 3, 4) &lt; (1, 2, 3, 4)) IS FALSE
 ((1, 2, 3, 4) &lt; (1, 2, 3, 5)) IS TRUE
 ((NULL, 1, NULL) = (NULL, 1, NULL)) IS UNKNOWN  
 ((NULL, 1, NULL) = (NULL, 2, NULL)) IS FALSE  
 ((NULL, 1, NULL) &lt;&gt; (NULL, 2, NULL)) IS TRUE  
 ((NULL, 1, 2) &lt;all operators&gt; (NULL, 1, 2)) IS UNKNOWN
 ((1, NULL, ...) &lt; (1, 2, ...)) IS UNKNOWN  
 ((1, NULL, ...) &lt; (2, NULL, ...)) IS TRUE
 ((2, NULL, ...) &lt; (1, NULL, ...)) IS FALSE
</pre>
<a name="N124B4" class="indexterm"></a>
<p>
<span class="bold"><strong>BETWEEN</strong></span>
</p>
<p>
<span class="emphasis"><em>between predicate</em></span>
</p>
<p>
<code class="literal">&lt;between predicate&gt; ::= &lt;row value
      predicand&gt; &lt;between predicate part 2&gt;</code>
</p>
<p>
<code class="literal">&lt;between predicate part 2&gt; ::= [ NOT ] BETWEEN [
      ASYMMETRIC | SYMMETRIC ] &lt;row value predicand&gt; AND &lt;row value
      predicand&gt;</code>
</p>
<p>Specify a range comparison. The default is ASYMMETRIC. The
      expression <code class="literal">X BETWEEN Y AND Z</code> is equivalent to
      <code class="literal">(X &gt;= Y AND X &lt;= Z)</code>. Therefore if Y &gt; Z, the
      BETWEEN expression is never true. The expression <code class="literal">X BETWEEN
      SYMMETRIC Y AND Z</code> is equivalent to <code class="literal">(X &gt;= Y AND X
      &lt;= Z) OR (X &gt;= Z AND X &lt;= Y)</code>. The expression
      <code class="literal">Z NOT BETWEEN ...</code> is equivalent to <code class="literal">NOT (Z
      BETWEEN ...)</code>. If any of the three <code class="literal">&lt;row value
      predicand&gt;</code> evaluates to NULL, the result is
      UNKNOWN.</p>
<a name="N124DD" class="indexterm"></a>
<p>
<span class="bold"><strong>IN</strong></span>
</p>
<p>
<span class="emphasis"><em>in predicate</em></span>
</p>
<p>
<code class="literal">&lt;in predicate&gt; ::= &lt;row value predicand&gt; [
      NOT ] IN &lt;in predicate value&gt;</code>
</p>
<p>
<code class="literal">&lt;in predicate value&gt; ::= &lt;table subquery&gt;
      | &lt;left paren&gt; &lt;in value list&gt; &lt;right paren&gt;
      </code>
</p>
<p>
<code class="literal">| &lt;left paren&gt; UNNEST &lt;left paren&gt;
      &lt;array value expression&gt; &lt;right paren&gt; &lt;right
      paren&gt;</code>
</p>
<p>
<code class="literal">&lt;in value list&gt; ::= &lt;row value expression&gt;
      [ { &lt;comma&gt; &lt;row value expression&gt; }...
      ]</code>
</p>
<p>Specify a quantified comparison. The expression <code class="literal">X NOT
      IN Y is</code> equivalent to <code class="literal">NOT (X IN Y)</code>. The
      <code class="literal">( &lt;in value list&gt; )</code> is converted into a table
      with one or more rows. The expression <code class="literal">X IN Y</code> is
      equivalent to <code class="literal">X = ANY Y</code>, which is a
      <code class="literal">&lt;quantified comparison predicate&gt;</code>.</p>
<p>If the <code class="literal">&lt;table subquery&gt;</code> returns no
      rows, the result is FALSE. Otherwise the <code class="literal">&lt;row value
      predicand&gt;</code> is compared one by one with each row of the
      <code class="literal">&lt;table subquery&gt;</code>.</p>
<p>If the comparison is TRUE for at least one row, the result is
      TRUE. If the comparison is FALSE for all rows, the result is FALSE.
      Otherwise the result is UNKNOWN.</p>
<p>HyperSQL supports an extension to the SQL Standard to allow an
      array to be used in the &lt;in predicate value&gt;. This is intended to
      be used with prepared statements where a variable length array of values
      can be used as the parameter value for each call. The example below
      shows how this is used in SQL. The JDBC code must create a new
      java.sql.Array object that contains the values and set the parameter
      with this array.</p>
<pre class="programlisting"> SELECT * FROM customer WHERE firstname IN ( UNNEST(?) )

 Connection conn;
 PreparedStatement ps;
 // conn and ps are instantiated here
 Array arr = conn.createArrayOf("INTEGER", new Integer[] {1, 2, 3});
 ps.setArray(1, arr);
 ResultSet rs = ps.executeQuery();
</pre>
<a name="N1251A" class="indexterm"></a>
<p>
<span class="bold"><strong>LIKE</strong></span>
</p>
<p>
<span class="emphasis"><em>like predicate</em></span>
</p>
<p>
<code class="literal">&lt;like predicate&gt; ::= &lt;character like
      predicate&gt; | &lt;octet like predicate&gt;</code>
</p>
<p>
<code class="literal">&lt;character like predicate&gt; ::= &lt;row value
      predicand&gt; [ NOT ] LIKE &lt;character pattern&gt; [ ESCAPE &lt;escape
      character&gt; ]</code>
</p>
<p>
<code class="literal">&lt;character pattern&gt; ::= &lt;character value
      expression&gt;</code>
</p>
<p>
<code class="literal">&lt;escape character&gt; ::= &lt;character value
      expression&gt;</code>
</p>
<p>
<code class="literal">&lt;octet like predicate&gt; ::= &lt;row value
      predicand&gt; [ NOT ] LIKE &lt;octet pattern&gt; [ ESCAPE &lt;escape
      octet&gt; ]</code>
</p>
<p>
<code class="literal">&lt;octet pattern&gt; ::= &lt;binary value
      expression&gt;</code>
</p>
<p>
<code class="literal">&lt;escape octet&gt; ::= &lt;binary value
      expression&gt;</code>
</p>
<p>Specify a pattern-match comparison for character or binary
      strings. The <code class="literal">&lt;row value predicand&gt;</code> is always a
      <code class="literal">&lt;string value expression&gt;</code> of character or
      binary type. The <code class="literal">&lt;character pattern&gt;</code> or
      <code class="literal">&lt;octet pattern&gt;</code> is a <code class="literal">&lt;string value
      expression&gt;</code> in which the underscore and percent characters
      have special meanings. The underscore means match any one character,
      while the percent means match a sequence of zero or more characters. The
      <code class="literal">&lt;escape character&gt;</code> or <code class="literal">&lt;escape
      octet&gt;</code> is also a <code class="literal">&lt;string value
      expression&gt;</code> that evaluates to a string of exactly one
      character length. If the underscore or the percent is required as normal
      characters in the pattern, the specified <code class="literal">&lt;escape
      character&gt;</code> or <code class="literal">&lt;escape octet&gt;</code> can
      be used in the pattern before the underscore or the percent. The
      <code class="literal">&lt;row value predicand&gt;</code> is compared with the
      <code class="literal">&lt;character pattern&gt;</code> and the result of
      comparison is returned. If any of the expressions in the predicate
      evaluates to NULL, the result of the predicate is UNKNOWN. The
      expression <code class="literal">A NOT LIKE B</code> is equivalent to <code class="literal">NOT
      (A LIKE B)</code>. If the length of the escape is not 1 or it is used
      in the pattern not immediately before an underscore or a percent
      character, an exception is raised.</p>
<a name="N12567" class="indexterm"></a>
<p>
<span class="bold"><strong>IS NULL</strong></span>
</p>
<p>
<span class="emphasis"><em>null predicate</em></span>
</p>
<p>
<code class="literal">&lt;null predicate&gt; ::= &lt;row value predicand&gt;
      IS [ NOT ] NULL</code>
</p>
<p>Specify a test for a null value. The expression <code class="literal">X IS
      NOT NULL</code> is NOT equivalent to <code class="literal">NOT (X IS
      NULL)</code>if the degree of the <code class="literal">&lt;row value
      predicand&gt;</code> is larger than 1. The rules are: If all fields
      are null, <code class="literal">X IS NULL</code> is TRUE and <code class="literal">X IS NOT
      NULL</code> is FALSE. If only some fields are null, both <code class="literal">X
      IS NULL</code> and <code class="literal">X IS NOT NULL</code> are FALSE. If all
      fields are not null, <code class="literal">X IS NULL</code> is FALSE and
      <code class="literal">X IS NOT NULL</code> is TRUE.</p>
<a name="N12593" class="indexterm"></a>
<p>
<span class="bold"><strong>ALL and ANY</strong></span>
</p>
<p>
<span class="emphasis"><em>quantified comparison predicate</em></span>
</p>
<p>
<code class="literal">&lt;quantified comparison predicate&gt; ::= &lt;row
      value predicand&gt; &lt;comp op&gt; &lt;quantifier&gt; &lt;table
      subquery&gt;</code>
</p>
<p>
<code class="literal">&lt;quantifier&gt; ::= &lt;all&gt; |
      &lt;some&gt;</code>
</p>
<p>
<code class="literal">&lt;all&gt; ::= ALL</code>
</p>
<p>
<code class="literal">&lt;some&gt; ::= SOME | ANY</code>
</p>
<p>Specify a quantified comparison. For a quantified comparison,
      the <code class="literal">&lt;row value predicand&gt;</code> is compared one by
      one with each row of the <code class="literal">&lt;table sub
      query&gt;</code>.</p>
<p>If the <code class="literal">&lt;table subquery&gt;</code> returns no
      rows, then if <code class="literal">ALL</code> is specified the result is TRUE,
      but if <code class="literal">SOME</code> or <code class="literal">ANY</code> is specified
      the result is FALSE.</p>
<p>If <code class="literal">ALL</code> is specified, if the comparison is
      TRUE for all rows, the result of the predicate is TRUE. If the
      comparison is FALSE for at least one row, the result is FALSE. Otherwise
      the result is UNKNOWN.</p>
<p>If <code class="literal">SOME</code> or <code class="literal">ANY</code> is
      specified, if the comparison is TRUE for at least one row, the result is
      TRUE. If the comparison is FALSE for all rows, the result is FALSE.
      Otherwise the result is UNKNOWN. Note that the IN predicate is
      equivalent to the SOME or ANY predicate using the <code class="literal">&lt;equals
      operator&gt;</code>.</p>
<p>In the examples below, the date of an invoice is compared to
      holidays in a given year. In the first example the invoice date must
      equal one of the holidays, in the second example it must be later than
      all holidays (later than the last holiday), in the third example it must
      be on or after some holiday (on or after the first holiday), and in the
      fourth example, it must be before all holidays (before the first
      holiday).</p>
<pre class="programlisting"> invoice_date = SOME (SELECT holiday_date FROM holidays)
 invoice_date &gt; ALL (SELECT holiday_date FROM holidays)
 invoice_date &gt;= ANY (SELECT holiday_date FROM holidays)
 invoice_date &lt; ALL (SELECT holiday_date FROM holidays)
</pre>
<a name="N125D5" class="indexterm"></a>
<p>
<span class="bold"><strong>EXISTS</strong></span>
</p>
<p>
<span class="emphasis"><em>exists predicate</em></span>
</p>
<p>
<code class="literal">&lt;exists predicate&gt; ::= EXISTS &lt;table
      subquery&gt;</code>
</p>
<p>Specify a test for a non-empty set. If the evaluation of
      <code class="literal">&lt;table subquery&gt;</code> results in one or more rows,
      then the expression is TRUE, otherwise FALSE.</p>
<a name="N125E9" class="indexterm"></a>
<p>
<span class="bold"><strong>UNIQUE</strong></span>
</p>
<p>
<span class="emphasis"><em>unique predicate</em></span>
</p>
<p>
<code class="literal">&lt;unique predicate&gt; ::= UNIQUE &lt;table
      subquery&gt;</code>
</p>
<p>Specify a test for the absence of duplicate rows. The result of
      the test is either TRUE or FALSE (never UNKNOWN). The rows of the
      <code class="literal">&lt;table subquery&gt;</code> that contain one or more NULL
      values are not considered for this test. If the rest of the rows are
      distinct from each other, the result of the test is TRUE, otherwise it
      is FALSE. The distinctness of rows X and Y is tested with the predicate
      <code class="literal">X IS DISTINCT FROM Y</code>.</p>
<a name="N12600" class="indexterm"></a>
<p>
<span class="bold"><strong>MATCH</strong></span>
</p>
<p>
<span class="emphasis"><em>match predicate</em></span>
</p>
<p>
<code class="literal">&lt;match predicate&gt; ::= &lt;row value
      predicand&gt; MATCH [ UNIQUE ] [ SIMPLE | PARTIAL | FULL ] &lt;table
      subquery&gt;</code>
</p>
<p>Specify a test for matching rows. The default is MATCH SIMPLE
      without UNIQUE. The result of the test is either TRUE or FALSE (never
      UNKNOWN).</p>
<p>The interpretation of NULL values is different from other
      predicates and quite counter-intuitive. If the <code class="literal">&lt;row value
      predicand&gt;</code> is NULL, or all of its fields are NULL, the
      result is TRUE.</p>
<p>Otherwise, the <code class="literal">&lt;row value predicand&gt;</code>
      is compared with each row of the <code class="literal">&lt;table
      subquery&gt;</code>.</p>
<p>If SIMPLE is specified, if some field of <code class="literal">&lt;row value
      predicate&gt;</code> is NULL, the result is TRUE. Otherwise if
      <code class="literal">&lt;row value predicate&gt; </code>is equal to one or more
      rows of <code class="literal">&lt;table subquery&gt;</code> the result is TRUE if
      UNIQUE is not specified, or if UNIQUE is specified and only one row
      matches. Otherwise the result is FALSE.</p>
<p>If PARTIAL is specified, if the non-null values
      <code class="literal">&lt;row value predicate&gt; </code>are equal to those in one
      or more rows of <code class="literal">&lt;table subquery&gt;</code> the result is
      TRUE if UNIQUE is not specified, or if UNIQUE is specified and only one
      row matches. Otherwise the result is FALSE.</p>
<p>If FULL is specified, if some field of <code class="literal">&lt;row value
      predicate&gt;</code> is NULL, the result is FALSE. Otherwise if
      <code class="literal">&lt;row value predicate&gt;</code> is equal to one or more
      rows of <code class="literal">&lt;table subquery&gt;</code> the result is TRUE if
      UNIQUE is not specified, or if UNIQUE is specified and only one row
      matches.</p>
<p>Note that MATCH can also used be used in FOREIGN KEY constraint
      definitions. The exact meaning is described in the <a class="link" href="#databaseobjects-chapt" title="Chapter&nbsp;4.&nbsp;Schemas and Database Objects">Schemas and Database Objects</a> chapter.</p>
<a name="N12642" class="indexterm"></a>
<p>
<span class="bold"><strong>OVERLAPS</strong></span>
</p>
<p>
<span class="emphasis"><em>overlaps predicate</em></span>
</p>
<p>
<code class="literal">&lt;overlaps predicate&gt; ::= &lt;row value
      predicand&gt; OVERLAPS &lt;row value predicand&gt;</code>
</p>
<p>Specify a test for an overlap between two datetime periods.
      Each <code class="literal">&lt;row value predicand&gt;</code> must have two fields
      and the fields together represent a datetime period. So the predicates
      is always in the form <code class="literal">(X1, X2) OVERLAPS (Y1, Y2)</code>. The
      first field is always a datetime value, while the second field is either
      a datetime value or an interval value.</p>
<p>If the second value is an interval value, it is replaced with
      the sum of the datetime value and itself, for example <code class="literal">(X1, X1 +
      X2) OVERLAPS (Y1, Y1 + Y 2)</code>.</p>
<p>If any of the values is NULL, the result is UNKNOWN.</p>
<p>The expression is true if there is there is any overlap between
      the two datetime periods. In the example below, the period is compared
      with a week long period ending yesterday.</p>
<pre class="programlisting"> (startdate, enddate) OVERLAPS (CURRENT_DATE - 7 DAY, CURRENT_DATE - 1 DAY)</pre>
<a name="N12664" class="indexterm"></a>
<p>
<span class="bold"><strong>IS DISTINCT</strong></span>
</p>
<p>
<span class="emphasis"><em>is distinct predicate</em></span>
</p>
<p>
<code class="literal">&lt;distinct predicate&gt; ::= &lt;row value
      predicand&gt; IS [ NOT ] DISTINCT FROM &lt;row value
      predicand&gt;</code>
</p>
<p>Specify a test of whether two row values are distinct. The
      result of the test is either TRUE or FALSE (never UNKNOWN). The
      <em class="glossterm">degree</em> the two <code class="literal">&lt;row value
      predicand&gt;</code> must be the same. Each field of the first
      <code class="literal">&lt;row value predicand&gt;</code> is compared to the field
      of the second <code class="literal">&lt;row value predicand&gt;</code> at the same
      position. If one field is NULL and the other is not NULL, or if the
      elements are NOT equal, then the result of the expression is TRUE. If no
      comparison result is TRUE, then the result of the predicate is FALSE.
      The expression <code class="literal">X IS NOT DISTINCT FROM Y</code> is equivalent
      to <code class="literal">NOT (X IS DISTINCT FORM Y)</code>. The following check
      returns true if startdate is not equal to enddate. It also returns true
      if either startdate or enddate is NULL. It returns false in other
      cases.</p>
<pre class="programlisting"> startdate IS DISTINCT FROM enddate</pre>
</div>
<div class="section" title="Aggregate Functions">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_aggregate_funcs"></a>Aggregate Functions</h3>
</div>
</div>
</div>
<a name="N1268D" class="indexterm"></a>
<p>
<span class="bold"><strong>aggregate function</strong></span>
</p>
<p>
<span class="emphasis"><em>aggregate function</em></span>
</p>
<p>
<code class="literal">&lt;aggregate function&gt; ::= COUNT &lt;left
      paren&gt; &lt;asterisk&gt; &lt;right paren&gt; [ &lt;filter clause&gt; ]
      | &lt;general set function&gt; [ &lt;filter clause&gt; ] | &lt;array
      aggregate function&gt; [ &lt;filter clause&gt; ]</code>
</p>
<p>
<code class="literal">&lt;general set function&gt; ::= &lt;set function
      type&gt; &lt;left paren&gt; [ &lt;set quantifier&gt; ] &lt;value
      expression&gt; &lt;right paren&gt;</code>
</p>
<p>
<code class="literal">&lt;set function type&gt; ::= &lt;computational
      operation&gt;</code>
</p>
<p>
<code class="literal">&lt;computational operation&gt; ::= AVG | MAX | MIN |
      SUM | EVERY | ANY | SOME | COUNT | STDDEV_POP | STDDEV_SAMP | VAR_SAMP |
      VAR_POP | MEDIAN</code>
</p>
<p>
<code class="literal">&lt;set quantifier&gt; ::= DISTINCT |
      ALL</code>
</p>
<p>
<code class="literal">&lt;filter clause&gt; ::= FILTER &lt;left paren&gt;
      WHERE &lt;search condition&gt; &lt;right paren&gt;</code>
</p>
<p>
<code class="literal">&lt;array aggregate function&gt; ::= ARRAY_AGG
      &lt;left paren&gt; [ &lt;set quantifier&gt; ] &lt;value expression&gt; [
      &lt;order by clause&gt; ] &lt;right paren&gt;</code>
</p>
<p>
<code class="literal">&lt;group concat function&gt; ::= GROUP_CONCAT
      &lt;left paren&gt; [ &lt;set quantifier&gt; ] &lt;value expression&gt; [
      &lt;order by clause&gt; ] [ SEPARATOR &lt;separator&gt; ] &lt;right
      paren&gt;</code>
</p>
<p>
<code class="literal">&lt;separator&gt; ::= &lt;character string
      literal&gt;</code>
</p>
<p>Specify a value computed from a collection of rows.</p>
<p>An aggregate function is used exclusively in a
      <code class="literal">&lt;query specification&gt;</code> and its use transforms a
      normal query into an aggregate query returning a single row instead of
      the multiple rows that the original query returns. For example,
      <code class="literal">SELECT acolumn &lt;table expression&gt;</code> is a query
      that returns the value of acolumn for all the rows the satisfy the given
      condition. But <code class="literal">SELECT MAX(acolumn) &lt;table
      expression&gt;</code> returns only one row, containing the largest
      value in that column. The query <code class="literal">SELECT COUNT(*) &lt;table
      expression&gt;</code> returns the count of rows, while
      <code class="literal">SELECT COUNT(acolumn) &lt;table expression&gt;</code>
      returns the count of rows where <code class="literal">acolumn IS NOT
      NULL</code>.</p>
<p>If the <code class="literal">&lt;table expression&gt;</code> is a grouped
      table (has a <code class="code">GROUP BY</code> clause), the aggregate function
      returns the result of the <code class="literal">COUNT</code> or
      <code class="literal">&lt;computational operation&gt;</code> for each group. In
      this case the result has the same number of rows as the original grouped
      query. For example <code class="literal">SELECT SUM(acolumn) &lt;table
      expression&gt;</code> when <code class="literal">&lt;table
      expression&gt;</code> has a <code class="literal">GROUP BY</code> clause,
      returns the sum of values for <code class="literal">acolumn</code> in each
      group.</p>
<p>If all values are NULL, the aggregate function returns
      NULL.</p>
<p>The SUM operations can be performed on numeric and interval
      expressions only. AVG and MEDIAN can be performed on numeric, interval
      or datetime expressions. AVG returns the average value, while SUM
      returns the sum of all values. MEDIAN returns the middle value in the
      sorted list of values.</p>
<p>MAX and MIN can be performed on all types of expressions and
      return the minimum or the maximum value.</p>
<p>
<code class="literal">COUNT(*)</code> returns the count of all values,
      including nulls, while <code class="literal">COUNT(&lt;value
      expression&gt;)</code> returns the count of non-NULL values. COUNT
      with DISTINCT also accepts multiple arguments. In this usage the
      distinct combinations of the arguments are counted. Examples
      below:</p>
<pre class="programlisting"> SELECT COUNT(DISTINCT firstname, lastname) FROM customer
 SELECT COUNT(DISTINCT (firstname, lastname)) FROM customer
</pre>
<p>The EVERY, ANY and SOME operations can be performed on boolean
      expressions only. EVERY returns TRUE if all the values are TRUE,
      otherwise FALSE. ANY and SOME are the same operation and return TRUE if
      one of the values is TRUE, otherwise it returns FALSE.</p>
<p>The other operations perform the statistical functions
      STDDEV_POP, STDDEV_SAMP, VAR_SAMP, VAR_POP on numeric values. NULL
      values are ignored in calculations.</p>
<p>User defined aggregate functions can be defined and used
      instead of the built-in aggregate functions. Syntax and examples are
      given in the <a class="link" href="#sqlroutines-chapt" title="Chapter&nbsp;8.&nbsp;SQL-Invoked Routines">SQL-Invoked Routines</a> chapter.</p>
<p>The <code class="code">&lt;filter clause&gt;</code> allows you to add a
      search condition. When the search condition evaluates to TRUE for a row,
      the row is included in aggregation. Otherwise the row is not included.
      In the example below a single query returns two different filtered
      counts:</p>
<pre class="programlisting"> SELECT COUNT(ITEM) FILTER (WHERE GENDER = 'F') AS "FEMALE COUNT", COUNT(ITEM) FILTER (WHERE GENDER = 'M') AS "MALE COUNT" FROM PEOPLE
</pre>
<p>ARRAY_AGG is different from all other aggregate functions, as
      it does not ignore the NULL values. This set function returns an array
      that contains all the values, for different rows, for the
      <code class="literal">&lt;value expression&gt;</code>. For example, if the
      <code class="literal">&lt;value expression&gt;</code> is a column reference, the
      SUM function adds the values for all the row together, while the
      ARRAY_AGG function adds the value for each row as a separate element of
      the array. ARRAY_AGG can include an optional <code class="literal">&lt;order by
      clause&gt;</code>. If this is used, the elements of the returned
      array are sorted according to the <code class="literal">&lt;order by
      clause&gt;</code>, which can reference all the available columns of
      the query, not just the <code class="literal">&lt;value expression&gt;</code> that
      is used as the ARRAY_AGG argument. The <code class="literal">&lt;order by
      clause&gt;</code> can have multiple elements (columns) and each
      element can include NULLS LAST or DESC qualifiers. No
      <code class="literal">&lt;separator&gt;</code> is used with this
      function.</p>
<p>GROUP_CONCAT is a specialised function derived from ARRAY_AGG.
      This function computes the array in the same way as ARRAY_AGG, removes
      all the NULL elements, then returns a string that is a concatenation of
      the elements of the array. If <code class="literal">&lt;separator&gt;</code> has
      been specified, it is used to separate the elements of the array.
      Otherwise the comma is used to separate the elements.</p>
<p>The example below shows a grouped query with ARRAY_AGG and
      GROUP_CONCAT. The CUSTOMER table that is included for tests in the
      DatabaseManager GUI app is the source of the data.</p>
<pre class="programlisting"> SELECT LASTNAME, ARRAY_AGG(FIRSTNAME ORDER BY FIRSTNAME) FROM Customer  GROUP BY LASTNAME

 LASTNAME  C2                                                         
 --------- ---------------------------------------------------------- 
 Steel     ARRAY['John','John','Laura','Robert']                      
 King      ARRAY['George','George','James','Julia','Robert','Robert'] 
 Sommer    ARRAY['Janet','Robert']                                    

 SELECT LASTNAME, GROUP_CONCAT(DISTINCT FIRSTNAME ORDER BY FIRSTNAME DESC SEPARATOR ' * ') FROM Customer  GROUP BY LASTNAME

 LASTNAME  C2                                                
 --------- ------------------------------------------------- 
 Steel     Robert * Laura * John                   
 King      Robert * Julia * James * George         
 Sommer    Robert * Janet</pre>
</div>
<div class="section" title="Other Syntax Elements">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_other_syntax_elements"></a>Other Syntax Elements</h3>
</div>
</div>
</div>
<a name="N12728" class="indexterm"></a>
<p>
<span class="bold"><strong>search condition</strong></span>
</p>
<p>
<span class="emphasis"><em>search condition</em></span>
</p>
<p>
<code class="literal">&lt;search condition&gt; ::= &lt;boolean value
      expression&gt;</code>
</p>
<p>Specify a condition that is TRUE, FALSE, or UNKNOWN. A search
      condition is often a predicate.</p>
<a name="N12739" class="indexterm"></a>
<p>
<span class="bold"><strong>PATH</strong></span>
</p>
<p>
<span class="emphasis"><em>path specification</em></span>
</p>
<p>
<code class="literal">&lt;path specification&gt; ::= PATH &lt;schema name
      list&gt;</code>
</p>
<p>
<code class="literal">&lt;schema name list&gt; ::= &lt;schema name&gt; [ {
      &lt;comma&gt; &lt;schema name&gt; }... ]</code>
</p>
<p>Specify an order for searching for a user-defined SQL-invoked
      routine. This is not currently supported by HyperSQL.</p>
<a name="N1274D" class="indexterm"></a>
<p>
<span class="bold"><strong>routine invocation</strong></span>
</p>
<p>
<span class="emphasis"><em>routine invocation</em></span>
</p>
<p>
<code class="literal">&lt;routine invocation&gt; ::= &lt;routine name&gt;
      &lt;SQL argument list&gt;</code>
</p>
<p>
<code class="literal">&lt;routine name&gt; ::= [ &lt;schema name&gt;
      &lt;period&gt; ] &lt;qualified identifier&gt;</code>
</p>
<p>
<code class="literal">&lt;SQL argument list&gt; ::= &lt;left paren&gt; [
      &lt;SQL argument&gt; [ { &lt;comma&gt; &lt;SQL argument&gt; }... ] ]
      &lt;right paren&gt;</code>
</p>
<p>
<code class="literal">&lt;SQL argument&gt; ::= &lt;value expression&gt; |
      &lt;target specification&gt;</code>
</p>
<p>Invoke an SQL-invoked routine. Examples are given in the <a class="link" href="#sqlroutines-chapt" title="Chapter&nbsp;8.&nbsp;SQL-Invoked Routines">SQL-Invoked Routines</a>
      chapter.</p>
<a name="N1276B" class="indexterm"></a>
<p>
<span class="bold"><strong>COLLATE</strong></span>
</p>
<p>
<span class="emphasis"><em>collate clause</em></span>
</p>
<p>
<code class="literal">&lt;collate clause&gt; ::= COLLATE &lt;collation
      name&gt;</code>
</p>
<p>Specify a collation for a column or for an ORDER BY expression.
      This collation is used for comparing the values of the column in
      different rows. Comparison can happens during the execution of SELECT,
      UPDATE or DELETE statements, when a UNIQUE constraint or index is
      defined on the column, or when the the rows are sorted by an ORDER BY
      clause.</p>
<a name="N1277C" class="indexterm"></a>
<p>
<span class="bold"><strong>CONSTRAINT</strong></span>
</p>
<p>
<span class="emphasis"><em>constraint name definition</em></span>
</p>
<p>
<code class="literal">&lt;constraint name definition&gt; ::= CONSTRAINT
      &lt;constraint name&gt;</code>
</p>
<p>
<code class="literal">&lt;constraint characteristics&gt; ::= &lt;constraint
      check time&gt; [ [ NOT ] DEFERRABLE ] | [ NOT ] DEFERRABLE [
      &lt;constraint check time&gt; ]</code>
</p>
<p>
<code class="literal">&lt;constraint check time&gt; ::= INITIALLY DEFERRED |
      INITIALLY IMMEDIATE</code>
</p>
<p>Specify the name of a constraint and its characteristics. This
      is an optional element of CONSTRAINT definition, not yet supported by
      HyperSQL.</p>
</div>
</div>
<div class="section" title="Data Access Statements">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="dac_data_access_statements"></a>Data Access Statements</h2>
</div>
</div>
</div>
<p>HyperSQL fully supports all of SQL-92 data access statements, plus
    some additions from SQL:2008. Due to time constraints, the current version
    of this Guide does not cover the subject fully. You are advised to consult
    an SQL book such as the recent O'Reilly title "SQL and Relational Theory"
    by C. J. Date.</p>
<p>Database queries are data access statements. The most commonly used
    data access statement is the SELECT statement, but there are other
    statements that perform a similar role. Data access statements access
    tables and return result tables. The returned result tables are falsely
    called result sets, as they are not necessarily sets of rows, but
    multisets of rows.</p>
<p>Result tables are formed by performing the following operations on
    base tables and views. These operations are loosely based on Relational
    Algebra.</p>
<p>
<em class="glossterm">JOIN</em> operations</p>
<p>
<em class="glossterm">SET</em> and <em class="glossterm">MULTISET</em>
    operations</p>
<p>
<em class="glossterm">SELECTION</em>
</p>
<p>
<em class="glossterm">PROJECTION</em>
</p>
<p>
<em class="glossterm">COMPUTING</em>
</p>
<p>
<em class="glossterm">COLUMN NAMING</em>
</p>
<p>
<em class="glossterm">GROUPING</em> and
    <em class="glossterm">AGGREGATION</em>
</p>
<p>
<em class="glossterm">SELECTION AFTER GROUPING OR
    AGGREGATION</em>
</p>
<p>
<em class="glossterm">SET and MULTISET (COLLECTION)
    OPERATIONS</em>
</p>
<p>
<em class="glossterm">ORDERING</em>
</p>
<p>
<em class="glossterm">SLICING</em>
</p>
<p>Conceptually, the operations are performed one by one in the above
    order if they apply to the given data access statement. In the example
    below a simple select statement is made more complex by adding various
    operations.</p>
<pre class="programlisting"> CREATE TABLE atable (a INT, b INT, c INT, d INT, e INT, f INT);
 /* in the next SELECT, no join is performed and no further operation takes place */
 SELECT * FROM atable
 /* in the next SELECT, selection is performed by the WHERE clause, with no further action */
 SELECT * FROM atable WHERE a + b = c
 /* in the next SELECT, projection is performed after the other operations */
 SELECT d, e, f FROM atable WHERE a + b = c
 /* in the next SELECT, computation is performed after projection */
 SELECT (d + e) / f FROM atable WHERE a + b = c
 /* in the next two SELECT statements, column naming is performed in different ways*/
 SELECT (a + e) / f AS calc, f AS div FROM atable WHERE a + b = c
 SELECT dcol, ecol, fcol FROM atable(acol, bcol, ccol, dcol, ecol, fcol) WHERE acol + bcol = ccol
 /* in the next SELECT, both grouping and aggregation is performed */
 SELECT d, e, SUM(f) FROM atable GROUP BY d, e
 /* in the next SELECT, selection is performed after grouping and aggregation is performed */
 SELECT d, e, SUM(f) FROM atable GROUP BY d, e HAVING SUM(f) &gt; 10
 /* in the next SELECT, a UNION is performed on two selects from the same table */
 SELECT d, e, f FROM atable WHERE d = 3 UNION SELECT a, b, c FROM atable WHERE a = 30
 /* in the next SELECT, ordering is performed */
 SELECT (a + e) / f AS calc, f AS div FROM atable WHERE a + b = c ORDER BY calc DESC, div NULLS LAST
 /* in the next SELECT, slicing is performed after ordering */
 SELECT * FROM atable WHERE a + b = c ORDER BY a FETCH 5 ROWS ONLY

</pre>
<p>The next sections discuss various types of tables and
    operations involved in data access statements.</p>
<div class="section" title="Select Statement">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_sql_select_statement"></a>Select Statement</h3>
</div>
</div>
</div>
<p>The SELECT statement itself does not cover all types of data
      access statements, which may combine multiple SELECT statements. The
      <code class="literal">&lt;query specification&gt;</code> is the most common data
      access statement and begins with the SELECT keyword.</p>
<a name="N127D5" class="indexterm"></a>
<p>
<span class="bold"><strong>SELECT STATEMENT</strong></span>
</p>
<p>
<span class="emphasis"><em>select statement (general)</em></span>
</p>
<p>Users generally refer to the SELECT statement when they mean a
      <code class="literal">&lt;query specification&gt;</code> or <code class="literal">&lt;query
      expression&gt;</code>. If a statement begins with SELECT and has no
      UNION or other set operations, then it is a <code class="literal">&lt;query
      specification&gt;</code>. Otherwise it is a <code class="literal">&lt;query
      expression&gt;</code>.</p>
</div>
<div class="section" title="Table">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_table"></a>Table</h3>
</div>
</div>
</div>
<p>In data access statements, a table can be a database table (or
      view) or an ephemeral table formed for the duration of the query. Some
      types of table are &lt;table primary&gt; and can participate in joins
      without the use of extra parentheses. The BNF in the Table Primary
      section below lists different types of &lt;table primary&gt;:</p>
<p>Tables can also be formed by specifying the values that are
      contained in them:</p>
<p>
<code class="literal">&lt;table value constructor&gt; ::= VALUES &lt;row
      value expression list&gt;</code>
</p>
<p>
<code class="literal">&lt;row value expression list&gt; ::= &lt;table row
      value expression&gt; [ { &lt;comma&gt; &lt;table row value
      expression&gt; }... ]</code>
</p>
<p>In the example below a table with two rows and 3 columns is
      constructed out of some values:</p>
<pre class="programlisting"> VALUES (12, 14, null), (10, 11, CURRENT_DATE)</pre>
<p>When a table is used directly in a UNION or similar operation,
      the keyword TABLE is used with the name:</p>
<p>
<code class="literal">&lt;explicit table&gt; ::= TABLE &lt;table or query
      name&gt;</code>
</p>
<p>In the examples below, all rows of the two tables are included
      in the union. The keyword TABLE is used in the first example. The two
      examples below are equivalent.</p>
<pre class="programlisting"> TABLE atable UNION TABLE anothertable
 SELECT * FROM atable UNION SELECT * FROM anothertable
</pre>
</div>
<div class="section" title="Subquery">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_subquery"></a>Subquery</h3>
</div>
</div>
</div>
<p>A subquery is simply a query expression in brackets. A query
      expression is usually a complete SELECT statement and is discussed in
      the rest of this chapter. A scalar subquery returns one row with one
      column. A row subquery returns one row with one or more columns. A table
      subquery returns zero or more rows with one or more columns. The
      distinction between different forms of subquery is syntactic. Different
      forms are allowed in different contexts. If a scalar subquery or a row
      subquery return more than one row, an exception is raised. If a scalar
      or row subquery returns no row, it is usually treated as returning a
      NULL. Depending on the context, this has different consequences.</p>
<p>
<code class="literal">&lt;scalar subquery&gt; ::= &lt;subquery&gt;
      </code>
</p>
<p>
<code class="literal">&lt;row subquery&gt; ::= &lt;subquery&gt;
      </code>
</p>
<p>
<code class="literal">&lt;table subquery&gt; ::= &lt;subquery&gt;
      </code>
</p>
<p>
<code class="literal">&lt;subquery&gt; ::= &lt;left paren&gt; &lt;query
      expression&gt; &lt;right paren&gt;</code>
</p>
</div>
<div class="section" title="Query Specification">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_query_specification"></a>Query Specification</h3>
</div>
</div>
</div>
<p>A query specification is also known as a SELECT statement. It is
      the most common form of <code class="literal">&lt;derived table&gt;</code> . A
      <code class="literal">&lt;table expression&gt;</code> is a base table, a view or
      any form of allowed derived table. The SELECT statement performs
      projection, naming, computing or aggregation on the rows of the
      <code class="literal">&lt;table expression&gt;</code> .</p>
<p>
<code class="literal">&lt;query specification&gt; ::= SELECT [ DISTINCT |
      ALL ] &lt;select list&gt; &lt;table expression&gt;</code>
</p>
<p>
<code class="literal">&lt;select list&gt; ::= &lt;asterisk&gt; | &lt;select
      sublist&gt; [ { &lt;comma&gt; &lt;select sublist&gt; }... ]
      </code>
</p>
<p>
<code class="literal">&lt;select sublist&gt; ::= &lt;derived column&gt; |
      &lt;qualified asterisk&gt; </code>
</p>
<p>
<code class="literal">&lt;qualified asterisk&gt; ::= &lt;asterisked
      identifier chain&gt; &lt;period&gt; &lt;asterisk&gt;</code>
</p>
<p>
<code class="literal">&lt;asterisked identifier chain&gt; ::= &lt;asterisked
      identifier&gt; [ { &lt;period&gt; &lt;asterisked identifier&gt; }... ]
      </code>
</p>
<p>
<code class="literal">&lt;asterisked identifier&gt; ::=
      &lt;identifier&gt;</code>
</p>
<p>
<code class="literal">&lt;derived column&gt; ::= &lt;value expression&gt; [
      &lt;as clause&gt; ] </code>
</p>
<p>
<code class="literal">&lt;as clause&gt; ::= [ AS ] &lt;column name&gt;
      </code>
</p>
<p>The qualifier DISTINCT or ALL apply to the results of the SELECT
      statement after all other operations have been performed. ALL simply
      returns the rows, while DISTINCT compares the rows and removes the
      duplicate ones.</p>
<p>Projection is performed by the <code class="literal">&lt;select
      list&gt;</code>.</p>
<p>A single <code class="literal">&lt;asterisk&gt;</code> means all columns of
      the <code class="literal">&lt;table expression&gt;</code> are included, in the
      same order as they appear in the <code class="literal">&lt;table
      expression&gt;</code>. An asterisk qualified by a table name means
      all the columns of the qualifier table name are included. If an
      unqualified asterisk is used, then no other items are allowed in the
      <code class="literal">&lt;select list&gt;</code>. When the the <code class="literal">&lt;table
      expression&gt;</code> is the direct result of NATURAL or USING joins,
      the use of <code class="literal">&lt;asterisk&gt;</code> includes the columns used
      for the join before the other columns. A qualified asterisk does not
      cover the join columns.</p>
<p>A derived column is a <code class="literal">&lt;value expression&gt;</code>,
      optionally named with the <code class="literal">&lt;as clause&gt;</code>. A
      <code class="literal">&lt;value expression&gt;</code> can be many things. Common
      types include: the name of a column in the <code class="literal">&lt;table
      expression&gt;</code>; an expression based on different columns or
      constant values; a function call; an aggregate function; a CASE WHEN
      expression.</p>
</div>
<div class="section" title="Table Expression">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_table_expression"></a>Table Expression</h3>
</div>
</div>
</div>
<p>A table expression is part of the SELECT statement and consists of
      the FROM clause with optional other clauses that performs selection (of
      rows) and grouping from the table(s) in the FROM clause.</p>
<p>
<code class="literal">&lt;table expression&gt; ::= &lt;from clause&gt; [
      &lt;where clause&gt; ] [ &lt;group by clause&gt; ] [ &lt;having
      clause&gt; ]</code>
</p>
<p>
<code class="literal">&lt;from clause&gt; ::= FROM &lt;table reference&gt; [ {
      &lt;comma&gt; &lt;table reference&gt; }... ]</code>
</p>
<p>
<code class="literal">&lt;table reference&gt; ::= &lt;table primary&gt; |
      &lt;joined table&gt; </code>
</p>
<p>
<code class="literal">&lt;table primary&gt; ::= &lt;table or query name&gt;
      [ [ AS ] &lt;correlation name&gt; [ &lt;left paren&gt; &lt;derived
      column list&gt; &lt;right paren&gt; ] ] </code>
</p>
<p>
<code class="literal">| &lt;derived table&gt; [ AS ] &lt;correlation
      name&gt; [ &lt;left paren&gt; &lt;derived column list&gt; &lt;right
      paren&gt; ] </code>
</p>
<p>
<code class="literal">| &lt;lateral derived table&gt; [ AS ] &lt;correlation
      name&gt; [ &lt;left paren&gt; &lt;derived column list&gt; &lt;right
      paren&gt; ] </code>
</p>
<p>
<code class="literal">| &lt;collection derived table&gt; [ AS ]
      &lt;correlation name&gt; [ &lt;left paren&gt; &lt;derived column
      list&gt; &lt;right paren&gt; ] </code>
</p>
<p>
<code class="literal">| &lt;table function derived table&gt; [ AS ]
      &lt;correlation name&gt; [ &lt;left paren&gt; &lt;derived column
      list&gt; &lt;right paren&gt; ] </code>
</p>
<p>
<code class="literal">| &lt;parenthesized joined table&gt; [ AS ]
      &lt;correlation name&gt; [ &lt;left paren&gt; &lt;derived column
      list&gt; &lt;right paren&gt; ] </code>
</p>
<p>
<code class="literal">&lt;where clause&gt; ::= WHERE &lt;boolean value
      expression&gt;</code>
</p>
<p>
<code class="literal">&lt;group by clause&gt; ::= GROUP BY [ &lt;set
      quantifier&gt; ] &lt;grouping element&gt; [ { &lt;comma&gt; &lt;grouping
      element&gt; }... ]</code>
</p>
<p>
<code class="literal">&lt;having clause&gt; ::= HAVING &lt;boolean value
      expression&gt;</code>
</p>
<p>The <code class="literal">&lt;from clause&gt;</code> contains one or more
      <code class="literal">&lt;table reference&gt;</code> separated by commas. A table
      reference is often a table or view name or a joined table.</p>
<p>The <code class="literal">&lt;where clause&gt;</code> filters the rows of
      the table in the &lt;from clause&gt; and removes the rows for which the
      search condition is not TRUE.</p>
<p>Table primary refers to different forms of table reference in the
      FROM clause.</p>
<div class="section" title="Table or Query Name">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="dac_table_primary"></a>Table or Query Name</h4>
</div>
</div>
</div>
<p>The simplest form of reference is simply a name. This is the
        name of a table, a view, a transition table in a trigger definition,
        or a query name specified in the WITH clause of a query
        expression.</p>
<p>
<code class="literal">&lt;table or query name&gt; ::= &lt;table name&gt; |
        &lt;transition table name&gt; | &lt;query name&gt;</code>
</p>
</div>
<div class="section" title="Derived Table">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="dac_derived_table"></a>Derived Table</h4>
</div>
</div>
</div>
<a name="N128B2" class="indexterm"></a>
<p>
<span class="bold"><strong>derived table</strong></span>
</p>
<p>A query expression that is enclosed in parentheses and returns
        from zero to many rows is a <code class="literal">&lt;table subquery&gt;</code>.
        In a <code class="literal">&lt;derived table&gt;</code> the query expression is
        self contained and cannot reference the columns of other table
        references. This is the traditional and most common form of use of a
        <code class="literal">&lt;table subquery&gt;</code>.</p>
<p>
<code class="literal">&lt;derived table&gt; ::= &lt;table
        subquery&gt;</code>
</p>
</div>
<div class="section" title="Lateral">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="dac_lateral"></a>Lateral</h4>
</div>
</div>
</div>
<a name="N128CD" class="indexterm"></a>
<p>
<span class="bold"><strong>LATERAL</strong></span>
</p>
<p>When the word LATERAL is used before a &lt;table subquery&gt;,
        it means the query expression can reference the columns of other table
        references that go before it.</p>
<p>
<code class="literal">&lt;lateral derived table&gt; ::= LATERAL &lt;table
        subquery&gt;</code>
</p>
<p>The use of &lt;lateral derived table&gt; completely transforms
        the way a query is written. For example, the two queries below are
        equivalent, but with different forms. The query with LATERAL is
        evaluated separately for each row of the first table that satisfies
        the WHERE condition. The example below uses the tables that are
        created and populated in DatabaseManagerSwing with the "Insert test
        data" menu option. The first query uses a scalar subquery to compute
        the sum of invoice values for each customer. The second query is
        equivalent and uses a join with a LATERAL table.</p>
<pre class="programlisting">SELECT firstname, lastname, (SELECT SUM(total) FROM invoice WHERE customerid = customer.id) s FROM customer

SELECT firstname, lastname, a.c FROM customer, LATERAL(SELECT SUM(total) FROM invoice WHERE customerid = customer.id) a (c)
</pre>
</div>
<div class="section" title="UNNEST">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="dac_unnest"></a>UNNEST</h4>
</div>
</div>
</div>
<a name="N128E3" class="indexterm"></a>
<p>
<span class="bold"><strong>UNNEST</strong></span>
</p>
<p>UNNEST is similar to LATERAL, but instead of a query expression,
        one or more expressions that return an array are used. These
        expressions are converted into a table which has one column for each
        expression and contains the elements of the array. If WITH ORDINALITY
        is used, an extra column that contains the index of each element is
        added to this table. The number or rows in the table equals the length
        of the largest arrays. The smaller arrays are padded with NULL values.
        If an &lt;array value expression&gt; evaluates to NULL, an empty array
        is used in its place. The array expression can contain references to
        any column of the table references preceding the current table
        reference.</p>
<p>
<code class="literal">&lt;collection derived table&gt; ::= UNNEST &lt;left
        paren&gt; &lt;array value expression&gt;, ... &lt;right paren&gt; [
        WITH ORDINALITY ]</code>
</p>
<p>The <code class="literal">&lt;array value expression&gt;</code> can be the
        result of a function call. If the arguments of the function call are
        values from the tables on the left of the UNNEST, then the function is
        called for each row of table.</p>
<p>In the first example below, UNNEST is used with the built
        in-function SEQUENCE_ARRAY to build a table containing dates for the
        last seven days and their ordinal position. In the second example, a
        select statement returns costs for the last seven days . In the third
        example, the WITH clause turns the two selects into named subqueries
        which are used in a SELECT statement that uses a LEFT join.</p>
<pre class="programlisting"> SELECT * FROM UNNEST(SEQUENCE_ARRAY(CURRENT_DATE - 7 DAY, CURRENT_DATE - 1 DAY, 1 DAY)) WITH ORDINALITY AS T(D, I)  

 D          I 
 ---------- - 
 2010-07-25 1 
 2010-07-26 2 
 2010-07-27 3 
 2010-07-28 4 
 2010-07-29 5 
 2010-07-30 6 
 2010-07-31 7 

 CREATE TABLE expenses (item_date DATE, cost DECIMAL(8,2))
 --
 SELECT item_date, SUM(cost) AS s FROM expenses WHERE item_date &gt;= CURRENT_DATE - 7 DAY GROUP BY item_date

 ITEM_DATE  S      
 ---------- ------ 
 2010-07-27 100.12 
 2010-07-29 50.45  

 WITH costs(i_d, s) AS (SELECT item_date, SUM(cost) AS s FROM expenses WHERE item_date &gt;= CURRENT_DATE - 7 DAY GROUP BY item_date),
 dates(d, i) AS (SELECT * FROM UNNEST(SEQUENCE_ARRAY(CURRENT_DATE - 7 DAY, CURRENT_DATE - 1 DAY, 1 DAY)) WITH ORDINALITY)   
 SELECT i, d, s FROM dates LEFT OUTER JOIN costs ON dates.d = costs.i_d

 I D          S      
 - ---------- ------ 
 1 2010-07-25 (null) 
 2 2010-07-26 (null) 
 3 2010-07-27 100.12 
 4 2010-07-28 (null) 
 5 2010-07-29 50.45  
 6 2010-07-30 (null) 
 7 2010-07-31 (null) 

</pre>
</div>
<div class="section" title="Table Function Derived Table">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="dac_table_function"></a>Table Function Derived Table</h4>
</div>
</div>
</div>
<a name="N128FE" class="indexterm"></a>
<p>
<span class="bold"><strong>Table Function Derived
        Table</strong></span>
</p>
<p>When TABLE is used in this context, the &lt;collection value
        expression&gt; must be the result of a function call to a built-in
        function or user-defined function that returns an array or a table.
        When the function returns an array, this array is converted into a
        table, similar to the way UNNEST operates. When the function returns a
        table, the result is a MULTISET and is used as is.</p>
<p>
<code class="literal">&lt;table function derived table&gt; ::= TABLE &lt;left
        paren&gt; &lt;collection value expression&gt; &lt;right
        paren&gt;</code>
</p>
</div>
<div class="section" title="Parenthesized Joined Table">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="dac_parens_j_table"></a>Parenthesized Joined Table</h4>
</div>
</div>
</div>
<p>A parenthesized joined table is simply a joined table contained
        in parentheses. Joined tables are discussed below.</p>
<p>
<code class="literal">&lt;parenthesized joined table&gt; ::= &lt;left
        paren&gt; &lt;parenthesized joined table&gt; &lt;right paren&gt; |
        &lt;left paren&gt; &lt;joined table&gt; &lt;right
        paren&gt;</code>
</p>
</div>
<div class="section" title="Column Name List">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="dac_col_name_list"></a>Column Name List</h4>
</div>
</div>
</div>
<a name="N12919" class="indexterm"></a>
<p>
<span class="bold"><strong>column name list</strong></span>
</p>
<p>The column list that is specified for the table reference must
        contain names that are unique within the list</p>
<p>
<code class="literal">&lt;derived column list&gt; ::= &lt;column name
        list&gt;</code>
</p>
<p>
<code class="literal">&lt;column name list&gt; ::= &lt;column name&gt; [ {
        &lt;comma&gt; &lt;column name&gt; }... ] </code>
</p>
</div>
</div>
<div class="section" title="Joined Table">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_joined_table"></a>Joined Table</h3>
</div>
</div>
</div>
<p>Joins are operators with two table as the operands, resulting in a
      third table, called joined table. All join operators are evaluated left
      to right, therefore, with multiple joins, the table resulting from the
      first join operator becomes an operand of the next join operator.
      Parentheses can be used to group sequences of joined tables and change
      the evaluation order. So if more than two tables are joined together
      with join operators, the end result is also a joined table. There are
      different types of join, each producing the result table in a different
      way.</p>
<p>
<code class="literal">&lt;joined table&gt; ::= &lt;cross join&gt; |
      &lt;qualified join&gt; | &lt;natural join&gt;</code>
</p>
<p>
<code class="literal">&lt;cross join&gt; ::= &lt;table reference&gt; CROSS JOIN
      &lt;table factor&gt; </code>
</p>
<p>
<code class="literal">&lt;qualified join&gt; ::= &lt;table reference&gt; | [
      &lt;join type&gt; ] JOIN &lt;table reference&gt; &lt;join
      specification&gt;</code>
</p>
<p>
<code class="literal">&lt;natural join&gt; ::= &lt;table reference&gt; NATURAL
      [ &lt;join type&gt; ] JOIN &lt;table factor&gt;</code>
</p>
<p>
<code class="literal">&lt;join specification&gt; ::= &lt;join condition&gt; |
      &lt;named columns join&gt;</code>
</p>
<p>
<code class="literal">&lt;join condition&gt; ::= ON &lt;search
      condition&gt;</code>
</p>
<p>
<code class="literal">&lt;named columns join&gt; ::= USING &lt;left paren&gt;
      &lt;join column list&gt; &lt;right paren&gt;</code>
</p>
<p>
<code class="literal">&lt;join type&gt; ::= INNER | &lt;outer join type&gt; [
      OUTER ] </code>
</p>
<p>
<code class="literal">&lt;outer join type&gt; ::= LEFT | RIGHT |
      FULL</code>
</p>
<p>
<code class="literal">&lt;join column list&gt; ::= &lt;column name
      list&gt;</code>
</p>
<a name="N1294E" class="indexterm"></a>
<p>
<span class="bold"><strong>CROSS JOIN</strong></span>
</p>
<p>The simplest form of join is CROSS JOIN. The CROSS JOIN of two
      tables is a table that has all the columns of the first table, followed
      by all the columns of the second table, in the original order. Each row
      of the first table is combined with each row of the second table to fill
      the rows of the new table. If the rows of each table form a set, then
      the rows of the CROSS JOIN table form the Cartesian product of the rows
      of the two table operands.</p>
<p>Conditions are not allowed as part of a cross join, which is
      simply <code class="literal">A CROSS JOIN B</code>. Any conditions in a WHERE
      clause are later applied to the table resulting from the cross
      join.</p>
<p>Tables in the FROM CLAUSE separated with commas, are equivalent to
      cross joins between the tables. Two joined tables separated with a
      comma, such as <code class="literal">A, B</code>, is equivalent to (A) CROSS JOIN
      (B), which means the joined tables A and B are populated separately
      before they are joined.</p>
<p>CROSS JOIN is not is not generally very useful, as it returns
      large result tables unless WHERE conditions are used.</p>
<a name="N12965" class="indexterm"></a>
<p>
<span class="bold"><strong>UNION JOIN</strong></span>
</p>
<p>The UNION JOIN has limited use in queries. The result table has
      the same columns as that of CROSS JOIN. Each row of the first table is
      extended to the right with nulls and added to the new table. Each row of
      the second table is extended to the left with nulls and added to the new
      table. The UNION JOIN is expressed as <code class="literal">A UNION JOIN B</code>.
      This should not be confused with <code class="literal">A UNION B</code>, which is
      a set operation. Union join is for special applications and is not
      commonly used.</p>
<a name="N12976" class="indexterm"></a>
<p>
<span class="bold"><strong>JOIN ... ON</strong></span>
</p>
<p>The condition join is similar to CROSS JOIN, but a condition is
      tested for each row of the new table and the row is created only if the
      condition is true. This form of join is expressed as <code class="literal">A JOIN B
      ON (&lt;search condition&gt;)</code>.</p>
<p>Equijoin is a condition join in which the search condition is an
      equality condition between on or more pairs of columns from the two
      table. Equijoin is the most commonly used type of join.</p>
<pre class="programlisting">SELECT a.*, b.* FROM a INNER JOIN b ON a.col_one = b.col_two
</pre>
<a name="N12988" class="indexterm"></a>
<p>
<span class="bold"><strong>JOIN ... USING</strong></span>
</p>
<a name="N12991" class="indexterm"></a>
<p>
<span class="bold"><strong>NATURAL JOIN</strong></span>
</p>
<p>Joins with USING or NATURAL keywords joins are similar to an
      equijoin but they cannot be replaced simply with an equijoin. The new
      table is formed with the specified or implied shared columns of the two
      tables, followed by the rest of the columns from each table. In NATURAL
      JOIN, the shared columns are all the column pairs that have the same
      name in the first and second table. In JOIN USING, only columns names
      that are specified by the USING clause are shared. The joins are
      expressed as <code class="literal">A NATURAL JOIN B</code>, and <code class="literal">A JOIN B
      USING (&lt;comma separated column name list&gt;)</code>.</p>
<p>The columns of the joined table are formed by the following
      procedures: In JOIN ... USING the shared columns are added to the joined
      table in the same order as they appear in the column name list. In
      NATURAL JOIN the shared columns are added to the joined table in the
      same order as they appear in the first table. In both forms of join, the
      non-shared columns of the first table are added in the order they appear
      in the first table, finally the non-shared columns of the second table
      are added in the order they appear in the second table.</p>
<p>The type of each shared column of the joined table is based on the
      type of the columns in the original tables. If the original types are
      not exactly the same, the type of the shared column is formed by type
      aggregation. Type aggregations selects a type that can represent values
      of both aggregated types. Simple type aggregation picks one of the
      types. For example SMALLINT and INTEGER, results in INTEGER, or
      VARCHAR(10) and VARCHAR(20) results in VARCHAR(20). More complex type
      aggregation inherits properties from both types. For example DECIMAL(8)
      and DECIMAL (6,2) results in DECIMAL (8,2).</p>
<p>In the examples below, the rows are joined exactly the same way,
      but the first query contains a.col_two and b.col_two together with all
      the rest of the columns of both tables, while the second query returns
      only one copy of col_two.</p>
<pre class="programlisting"> SELECT * FROM a INNER JOIN b ON a.col_two = b.col_two
 SELECT * FROM a INNER JOIN b USING (col_two)
</pre>
<a name="N129AA" class="indexterm"></a>
<p>
<span class="bold"><strong>OUTER JOIN</strong></span>
</p>
<p>LEFT, RIGHT and FULL OUTER JOIN</p>
<p>The three qualifiers can be added to all types of JOIN except
      CROSS JOIN and UNION JOIN. First the new table is populated with the
      rows from the original join. If LEFT is specified, all the rows from the
      first table that did not make it into the new table are extended to the
      right with nulls and added to the table. If RIGHT is specified, all the
      rows from the second table that did not make it into the new table are
      extended to the left with nulls and added to the table. If FULL is
      specified, the addition of leftover rows is performed from both the
      first and the second table. These forms are expressed by prefixing the
      join specification with the given keyword. For example <code class="literal">A LEFT
      OUTER JOIN B ON (&lt;search condition&gt;)</code> or <code class="literal">A
      NATURAL FULL OUTER JOIN B</code> or <code class="literal">A FULL OUTER JOIN B
      USING (&lt;comma separated column name list&gt;)</code>.</p>
<pre class="programlisting"> SELECT a.*, b.* FROM a LEFT OUTER JOIN b ON a.col_one = b.col_two
</pre>
</div>
<div class="section" title="Selection">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_selection"></a>Selection</h3>
</div>
</div>
</div>
<p>Despite the name, selection has nothing to do with the list of
      columns in a SELECT statement. In fact, it refers to the search
      condition used to limit the rows that from a result table (selection of
      rows, not columns). In SQL, simple selection is expressed with a WHERE
      condition appended to a single table or a joined table. In some cases,
      this method of selection is the only method available. For example in
      DELETE and UPDATE statements. But when it is possible to perform the
      selection with join conditions, this is the better method, as it results
      in a clearer expression of the query.</p>
</div>
<div class="section" title="Projection">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_projection"></a>Projection</h3>
</div>
</div>
</div>
<p>Projection is selection of the columns from a simple or joined
      table to form a result table. Explicit projection is performed in the
      SELECT statement by specifying the select column list. Some form of
      projection is also performed in JOIN ... USING and NATURAL JOIN.</p>
<p>The joined table has columns that are formed according to the
      rules mentioned above. But in many cases, not all the columns are
      necessary for the intended operation. If the statement is in the form,
      SELECT * FROM &lt;joined table&gt;, then all the columns of &lt;joined
      table&gt; are returned. But normally, the columns to be returned are
      specified after the SELECT keyword, separated from each other with
      commas.</p>
</div>
<div class="section" title="Computed Columns">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_computed_columns"></a>Computed Columns</h3>
</div>
</div>
</div>
<p>In the select list, it is possible to use expressions that
      reference any columns of &lt;joined table&gt;. Each of these expressions
      forms a computed column. It is computed for each row of the result
      table, using the values of the columns of the &lt;joined table&gt; for
      that row.</p>
</div>
<div class="section" title="Naming">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_naming"></a>Naming</h3>
</div>
</div>
</div>
<p>Naming is used to hide the original names of tables or table
      columns and to replace them with new names in the scope of the query.
      Naming is also used for defining names for computed columns.</p>
<p>Without explicit naming, the name of a column is a predefined
      name. If the column is a column of a table, or is a named parameter, the
      name is of the table column or parameter is used. Otherwise it is
      generated by the database engine. HyperSQL generates column names such
      as C1, C2, etc. As generated naming is implementation defined according
      to the SQL Standard, it is better to explicitly name the computed and
      derived columns in your applications.</p>
<a name="N129DE" class="indexterm"></a>
<p>
<span class="bold"><strong>Naming in Joined
      Table</strong></span>
</p>
<p>Naming is performed by adding a new name after a table's real name
      and by adding a list of column names after the new table name. Both
      table naming and column naming are optional, but table naming is
      required for column naming. The expression <code class="literal">A [AS] X (&lt;comma
      separated column name list&gt;)</code> means table A is used in the
      query expression as table X and its columns are named as in the given
      list. The original name A, or its original column names, are not visible
      in the scope of the query. The BNF is given below. The
      <code class="literal">&lt;correlation name&gt;</code> can be the same or different
      from the name of the table. The <code class="literal">&lt;derived column
      list&gt;</code> is a comma separated list of column names. The degree
      of this list must be equal to the degree of the table. The column names
      in the list must be distinct. They can be the same or different from the
      names of the table's columns.</p>
<p>
<code class="literal">&lt;table or query name&gt; [ [ AS ] &lt;correlation
      name&gt; [ &lt;left paren&gt; &lt;derived column list&gt; &lt;right
      paren&gt; ] ]</code>
</p>
<p>In the examples below, the columns of the original tables are
      named (a, b, c, d, e, f). The two queries are equivalent. In the second
      query, the table and its columns are renamed and the new names are used
      in the WHERE clauses:</p>
<pre class="programlisting"> CREATE TABLE atable (a INT, b INT, c INT, d INT, e INT, f INT);
 SELECT d, e, f FROM atable WHERE a + b = c
 SELECT x, y, z FROM atable AS t (u, v, w, x, y, z)  WHERE u + v = w</pre>
<a name="N129F9" class="indexterm"></a>
<p>
<span class="bold"><strong>Naming in Select
      List</strong></span>
</p>
<p>Naming in the SELECT list logically takes place after naming in
      the joined table. The new names for columns are not visible in the
      immediate query expression or query expression. They become visible in
      the ORDER BY clause and in the result table that is returned to the
      user. Or if the query expression is used as a derived table in an
      enclosing query expression.</p>
<p>In the example below, the query is on the same table but with
      column renaming in the Select list. The new names are used in the ORDER
      BY clause:</p>
<pre class="programlisting"> SELECT x + y AS xysum, y + z AS yzsum FROM atable AS t (u, v, w, x, y, z)  WHERE u + v = w ORDER BY xysum, yzsum</pre>
<p>If the names <code class="literal">xysum</code> or <code class="literal">yzsum</code>
      are not used, the computed columns cannot be referenced in the ORDER BY
      list.</p>
<a name="N12A10" class="indexterm"></a>
<p>
<span class="bold"><strong>Name Resolution</strong></span>
</p>
<p>In a joined table, if a column name appears in tables on both
      sides then any reference to the name must use the table name in order to
      specify which table is being referred to.</p>
</div>
<div class="section" title="Grouping Operations">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_grouping_operations"></a>Grouping Operations</h3>
</div>
</div>
</div>
<a name="N12A1F" class="indexterm"></a>
<p>
<span class="bold"><strong>Grouping Operations</strong></span>
</p>
<p>Grouping results in the elimination of duplicate rows. A grouping
      operation is performed after the operations discussed above. A simple
      form of grouping is performed by the use of DISTINCT after SELECT. This
      eliminates all the duplicate rows (rows that have the same value in each
      of their columns when compared to another row). The other form of
      grouping is performed with the GROUP BY clause. This form is usually
      used together with aggregation.</p>
<a name="N12A2A" class="indexterm"></a>
<p>
<span class="bold"><strong>GROUP BY</strong></span>
</p>
<p>
<code class="literal">&lt;group by clause&gt; ::= GROUP BY &lt;grouping
      element&gt; [ { &lt;comma&gt; &lt;grouping element&gt; }...
      ]</code>
</p>
<p>
<code class="literal">&lt;grouping element&gt; ::= &lt;column reference&gt;
      [ &lt;collate clause&gt; ] </code>
</p>
<p>The <code class="literal">&lt;group by clause&gt;</code> is a comma
      separated list of columns of the table in the <code class="literal">&lt;from
      clause&gt;</code> or expressions based on the columns.</p>
<p>When a <code class="literal">&lt;group by clause&gt;</code> is used, only
      the columns used in the <code class="literal">&lt;group by clause&gt;</code> or
      expressions used there, can be used in the <code class="literal">&lt;select
      list&gt;</code>, together with any <code class="literal">&lt;aggregate
      function&gt;</code> on other columns. In other words, the column
      names or expressions listed in the GROUP BY cluase dictate what can be
      used in the <code class="literal">&lt;select list&gt;</code>. After the rows of
      the table formed by the <code class="literal">&lt;from clause&gt;</code> and the
      <code class="literal">&lt;where clause&gt;</code> are finalised, the grouping
      operation groups together the rows that have the same values in the
      columns of the <code class="literal">&lt;group by clause&gt;</code>. Then any
      <code class="literal">&lt;aggregate function&gt;</code> in the <code class="literal">&lt;select
      list&gt;</code> is performed on each group, and for each group, a row
      is formed that contains the values of the columns of the
      <code class="literal">&lt;group by clause&gt;</code> and the values returned from
      each <code class="literal">&lt;aggregate function&gt;</code>.</p>
<p>When the type of <code class="literal">&lt;column reference&gt;</code> is
      character string, the <code class="literal">&lt;collate clause&gt;</code> can be
      used to specify the collation used for grouping the rows. For example, a
      collation that is not case sensitive can be used, or a collation for a
      different language than the original collation of the column.</p>
<p>In the first example below, a simple column reference is used in
      GROUP BY, while in the second example, an expression is
      used.</p>
<pre class="programlisting"> CREATE TABLE atable (a INT, b INT, c INT, d INT, e INT, f INT);
 SELECT d, e, f FROM atable WHERE a + b = c GROUP BY d, e, f
 SELECT d + e, SUM(f) FROM atable WHERE a + b = c GROUP BY d + e HAVING SUM(f) &gt; 2 AND d + e &gt; 4
</pre>
<p>A <code class="literal">&lt;having clause&gt;</code> filters the rows of the
      table that is formed after applying the <code class="literal">&lt;group by
      clause&gt;</code> using its search condition. The search condition
      must be an expression based on the expressions in the GROUP BY list or
      the aggregate functions used.</p>
<a name="N12A7B" class="indexterm"></a>
<p>
<span class="bold"><strong>DISTINCT</strong></span>
</p>
<p>
<code class="literal">SELECT DISTINCT</code>
</p>
<p>When the keyword DISTINCT is used after SELECT, it works as a
      shortcut replacement for a simple GROUP BY clause. The expressions in
      the SELECT list are used directly as the <code class="literal">&lt;group by
      clause&gt;</code>. The following examples of SELECT DISTINCT and
      SELECT with GROUP BY are equivalent.</p>
<pre class="programlisting"> SELECT DISTINCT d, e + f FROM atable WHERE a + b = c
 SELECT d, e + f FROM atable WHERE a + b = c GROUP BY d, e + f
</pre>
</div>
<div class="section" title="Aggregation">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_aggregation"></a>Aggregation</h3>
</div>
</div>
</div>
<p>Aggregation is an operation that computes a single value from the
      values of a column over several rows. The operation is performed with an
      aggregate function. The simplest form of aggregation is counting,
      performed by the COUNT function.</p>
<p>Other common aggregate functions return the maximum, minimum and
      average value among the values in different rows. Aggregate functions
      were discussed earlier in this chapter.</p>
</div>
<div class="section" title="Set Operations">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_set_operations"></a>Set Operations</h3>
</div>
</div>
</div>
<a name="N12A9A" class="indexterm"></a>
<p>
<span class="bold"><strong>Set and Multiset
      Operations</strong></span>
</p>
<p>While join operations generally result in laterally expanded
      tables, SET and COLLECTION operations are performed on two tables that
      have the same degree and result in a table of the same degree. The SET
      operations are UNION, INTERSECT and EXCEPT (difference). When each of
      these operations is performed on two tables, the collection of rows in
      each table and in the result is reduced to a set of rows, by eliminating
      duplicates. The set operations are then performed on the two tables,
      resulting in the new table which itself is a set of rows. Collection
      operations are similar but the tables are not reduced to sets before or
      after the operation and the result is not necessarily a set, but a
      collection of rows.</p>
<p>The set operations on two tables A and B are: <code class="literal">A UNION
      [DISTINCT] B</code>, <code class="literal">A INTERSECT [DISTINCT] B</code> and
      <code class="literal">A EXCEPT [DISTINCT] B</code>. The result table is formed in
      the following way: The UNION operation adds all the rows from A and B
      into the new table, but avoids copying duplicate rows. The INTERSECT
      operation copies only those rows from each table that also exist in the
      other table, but avoids copying duplicate rows. The EXCEPT operation
      copies those rows from the first table which do not exist in the second
      table, but avoids copying duplicate rows.</p>
<p>The collection operations are similar to the set operations, but
      can return duplicate rows. They are <code class="literal">A UNION ALL B</code>,
      <code class="literal">A INTERSECT ALL B</code> and <code class="literal">A EXCEPT ALL
      B</code>. The UNION ALL operation adds all the rows from A and B into
      the new table. The INTERSECT operation copies only those rows from each
      table that also exist in the other table. If n copies of a rows exists
      in one table, and m copies in the other table, the number of copies in
      the result table is the smaller of n and m. The EXCEPT operation copies
      those rows from the first table which do not exist in the second table.
      If n copies of a row exist in the first table and m copies in the second
      table the number of copies in the result table is n-m, or if n &lt; m,
      then zero.</p>
</div>
<div class="section" title="With Clause and Recursive Queries">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_with_clause"></a>With Clause and Recursive Queries</h3>
</div>
</div>
</div>
<p>The optional WITH clause can be used in a query expression. The
      WITH clause lists one or more named ephemeral tables that can be
      referenced in the query expression body. The ephemeral tables are
      created and populated before the rest of the query expression is
      executed. Their contents do not change during the execution of the
      <code class="literal">&lt;query expression body&gt;</code>.</p>
<p>
<code class="literal">&lt;with clause&gt; ::= WITH [ RECURSIVE ] &lt;with
      list&gt;</code>
</p>
<p>
<code class="literal">&lt;with list&gt; ::= &lt;with list element&gt; [ {
      &lt;comma&gt; &lt;with list element&gt; }... ] </code>
</p>
<p>
<code class="literal">&lt;with list element&gt; ::= &lt;query name&gt; [
      &lt;left paren&gt; &lt;with column list&gt; &lt;right paren&gt; ] AS
      &lt;left paren&gt; &lt;query expression&gt; &lt;right paren&gt;
      </code>
</p>
<p>
<code class="literal">&lt;with column list&gt; ::= &lt;column name
      list&gt;</code>
</p>
<p>An example of the use of the WITH clause is given above under
      UNNEST. The <code class="literal">&lt;query expression&gt;</code> in the WITH
      clause is evaluated once and its result table can be referenced in the
      body of the main <code class="literal">&lt;query expression body&gt;</code> using
      the specified &lt;query name&gt;.</p>
<p>The RECURSIVE keyword changes the way the elements of the
      <code class="literal">&lt;with list&gt;</code> are interpreted. The
      <code class="literal">&lt;query expression&gt;</code> contained in the
      <code class="literal">&lt;with list element&gt;</code> must be the UNION or UNION
      ALL of two &lt;query expression body&gt; elements (simple VALUES or
      SELECT statements). The left element of the UNION is evaluated first and
      its result becomes the result of the <code class="literal">&lt;with list
      element&gt;</code>. After this step, the current result of the
      &lt;with list element&gt; is referenced in the right element (a SELECT
      statement) of the UNION, the UNION is performed between the result and
      previous result of the <code class="literal">&lt;with list element&gt;</code>,
      which is enlarged by this operation. The UNION operation is performed
      again and again, until the result of the <code class="literal">&lt;with list
      element&gt;</code> stops changing. The result of the
      <code class="literal">&lt;with list element&gt;</code> is now complete and is
      later used in the execution of the <code class="literal">&lt;query expression
      body&gt;</code>. When RECURSIVE is used, the <code class="literal">&lt;with column
      list&gt;</code> must be defined.</p>
<p>HyperSQL limits recursion to 265 rounds. If this is exceeded, an
      error is raised.</p>
<p>A trivial example of a recursive query is given below. Note the
      first column GEN. For example, if each row of the table represents a
      member of a family of dogs, together with its parent, the first column
      of the result indicates the calculated generation of each dog, ranging
      from first to fourth generation.</p>
<pre class="programlisting"> CREATE TABLE pptree (pid INT, id INT);
 INSERT INTO pptree VALUES (NULL, 1) ,(1,2), (1,3),(2,4),(4,5),(3,6),(3,7);

 WITH RECURSIVE tree (gen, par, child) AS (
   VALUES(1, CAST(null as int), 1)
   UNION
   SELECT gen + 1, pid, id FROM pptree, tree WHERE pid = child
   ) SELECT * FROM tree;

 GEN PAR    CHILD 
 --- ------ ----- 
 1   (null) 1     
 2   1      2     
 2   1      3     
 3   2      4     
 3   3      6     
 3   3      7     
 4   4      5</pre>
<p>if recursive queries become complex they also become very
      difficult to develop and debug. HyperSQL provides an alternative to this
      with user-defined SQL functions which return tables. Functions can
      perform any complex, repetitive task with better control, using loops,
      variables and, if necessary, recursion.</p>
</div>
<div class="section" title="Query Expression">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_query_expression"></a>Query Expression</h3>
</div>
</div>
</div>
<p>A query expression consists of an optional WITH clause and a query
      expression body. The optional WITH clause lists one or more named
      ephemeral tables that can be referenced, just like the database tables
      in the query expression body.</p>
<p>
<code class="literal">&lt;query expression&gt; ::= [ &lt;with clause&gt; ]
      &lt;query expression body&gt;</code>
</p>
<p>A query expression body refers to a table formed by using UNION
      and other set operations. The query expression body is evaluated from
      left to right and the INTERSECT operator has precedence over the UNION
      and EXCEPT operators. A simplified BNF is given below:</p>
<p>
<code class="literal">&lt;query expression body&gt; ::= &lt;query term&gt; |
      &lt;query expression body&gt; UNION | EXCEPT [ ALL | DISTINCT ] [
      &lt;corresponding spec&gt; ] &lt;query term&gt;</code>
</p>
<p>
<code class="literal">&lt;query term&gt; ::= &lt;query primary&gt; |
      &lt;query term&gt; INTERSECT [ ALL | DISTINCT ] [ &lt;corresponding
      spec&gt; ] &lt;query term&gt;</code>
</p>
<p>
<code class="literal">&lt;query primary&gt; ::= &lt;simple table&gt; |
      &lt;left paren&gt; &lt;query expression body&gt; [ &lt;order by
      clause&gt; ] [ &lt;result offset clause&gt; ] [ &lt;fetch first
      clause&gt; ] &lt;right paren&gt;</code>
</p>
<p>
<code class="literal">&lt;simple table&gt; ::= &lt;query specification&gt; |
      &lt;table value constructor&gt; | &lt;explicit table&gt; &lt;explicit
      table&gt; ::= TABLE &lt;table or query name&gt;</code>
</p>
<p>
<code class="literal">&lt;corresponding spec&gt; ::= CORRESPONDING [ BY
      &lt;left paren&gt; &lt;column name list&gt; &lt;right paren&gt;
      ]</code>
</p>
<p>A <code class="literal">&lt;query term&gt;</code> and a <code class="literal">&lt;query
      primary&gt;</code> can be a SELECT statement, an
      <code class="literal">&lt;explicit table&gt;</code>, or a <code class="literal">&lt;table value
      constructor&gt;</code>.</p>
<p>The CORRESPONDING clause is optional. If it is not specified, then
      the <code class="literal">&lt;query term&gt;</code> and the <code class="literal">&lt;query
      primary&gt;</code> must have the same number of columns. If
      CORRESPONDING is specified, the two sides need not have the same number
      of columns. If no column list is used with CORRESPONDING, then all the
      column names that are common in the tables on two sides are used in the
      order in which they appear in the first table. If a columns list is
      used, it allows you to select only some columns of the tables on the
      left and right side to create the new table. In the example below the
      columns named u and v from the two SELECT statements are used to create
      the UNION table.</p>
<pre class="programlisting"> SELECT * FROM atable UNION CORRESPONDING BY (u, v) SELECT * FROM anothertable
</pre>
<p>The type of each column of the query expression is determined
      by combining the types of the corresponding columns from the two
      participating tables.</p>
</div>
<div class="section" title="Ordering">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_ordering"></a>Ordering</h3>
</div>
</div>
</div>
<p>When the rows of the result table have been formed, it is possible
      to specify the order in which they are returned to the user. The ORDER
      BY clause is used to specify the columns used for ordering, and whether
      ascending or descending ordering is used. It can also specify whether
      NULL values are returned first or last.</p>
<pre class="programlisting"> SELECT x + y AS xysum, y + z AS yzsum FROM atable AS t (u, v, w, x, y, z)  WHERE u + v = w ORDER BY xysum NULLS LAST, yzsum NULLS FIRST</pre>
<p>The ORDER BY clause specifies one or more <code class="literal">&lt;value
      expressions&gt;</code>. The list of rows is sorted according to the
      first <code class="literal">&lt;value expression&gt;</code>. When some rows are
      sorted equal then they are sorted according to the next
      <code class="literal">&lt;value expression&gt;</code> and so on.</p>
<p>
<code class="literal">&lt;order by clause&gt; ::= ORDER BY &lt;sort
      specification&gt; [ { &lt;comma&gt; &lt;sort specification&gt; }...
      ]</code>
</p>
<p>
<code class="literal">&lt;sort specification&gt; ::= &lt;value expression&gt; [
      &lt;collate clause&gt; ] [ ASC | DESC ] [ NULLS FIRST | NULLS LAST
      ]</code>
</p>
<p>The defaults are ASC and NULLS FIRST. Two database properties SQL
      NULLS FIRST and SQL NULLS ORDER can be modified to change the default
      behaviour.</p>
<p>A collation is used for columns of an ORDER BY expression that are
      of the type CHAR or VARCHAR. If a <code class="literal">&lt;collate
      clause&gt;</code> is not specified then the collation of the column,
      or the default collation of the database is used.</p>
<p>The default collation for a database is ASCII, with lowercase
      letters sorted after all uppercase letters. The example below shows the
      effect of collation on an ordered list.</p>
<pre class="programlisting"> -- default collation collation for the database is ASCII
 SELECT id, lastname FROM customer ORDER BY lastname
 ID LASTNAME 
 -- -------- 
 40 Clancy   
 36 King     
 35 White    
 6  king

 -- a language collation is used, it treats king and King as adjacent entries
 SELECT id, lastname FROM customer ORDER BY lastname COLLATE "English"
 ID LASTNAME 
 -- -------- 
 40 Clancy   
 6  king     
 36 King     
 35 White
</pre>
<p>In the above example, if the LASTNAME column is itself
      defined in the table definition with <code class="literal">COLLATE
      "English"</code>, then the COLLATE clause is not necessary in the
      ORDER BY expression.</p>
<p>An ORDER BY operation can sometimes be optimised by the engine
      when it can use the same index for accessing the table data and
      ordering. Optimisation can happen both with DESC + NULLS LAST and ASC +
      NULLS FIRST.</p>
<a name="N12B5C" class="indexterm"></a>
<p>
<span class="bold"><strong>sort specification
      list</strong></span>
</p>
<p>
<span class="emphasis"><em>sort specification list</em></span>
</p>
<p>
<code class="literal">&lt;sort specification list&gt; ::= &lt;value
      expression&gt; [ASC | DESC] [NULLS FIRST | NULLS
      LAST]</code>
</p>
<p>Specify a sort order. A sort operation is performed on the
      result of a <code class="literal">&lt;query expression&gt;</code> or
      <code class="literal">&lt;query specification&gt;</code> and sorts the result
      according to one or more <code class="literal">&lt;value expression&gt;</code>.
      The <code class="literal">&lt;value expression&gt;</code> is usually a single
      column of the result, but in some cases it can be a column of the
      <code class="literal">&lt;table expression&gt;</code> that is not used in the
      select list. The default is ASC and NULLS FIRST.</p>
</div>
<div class="section" title="Slicing">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_slicing"></a>Slicing</h3>
</div>
</div>
</div>
<p>A different form of limiting the rows can be performed on the
      result table after it has been formed according to all the other
      operations (selection, grouping, ordering etc.). This is specified by
      the FETCH ... ROWS and OFFSET clauses of a SELECT statement. In this
      form, the specified OFFSET rows are removed from start of the table,
      then up to the specified FETCH rows are kept and the rest of the rows
      are discarded.</p>
<p>
<code class="literal">&lt;result offset clause&gt; ::= OFFSET &lt;offset row
      count&gt; { ROW | ROWS }</code>
</p>
<p>
<code class="literal">&lt;fetch first clause&gt; ::= FETCH { FIRST | NEXT } [
      &lt;fetch first row count&gt; ] { ROW | ROWS } ONLY [ USING INDEX
      ]</code>
</p>
<p>
<code class="literal">&lt;limit clause&gt; ::= LIMIT &lt;fetch first row
      count&gt; [ USING INDEX ]</code>
</p>
<p>A slicing operation takes the result set that has been already
      processed and ordered. It then discards the specified number of rows
      from the start of the result set and returns the specified number of
      rows after the discarded rows. The &lt;offset row count&gt; and
      &lt;fetch first row count&gt; can be constants, dynamic variables,
      routine parameters, or routine variables. The type of the constants must
      be INTEGER.</p>
<pre class="programlisting"> SELECT a, b FROM atable WHERE d &lt; 5 ORDER BY absum OFFSET 3 FETCH 2 ROWS ONLY 
 SELECT a, b FROM atable WHERE d &lt; 5 ORDER BY absum OFFSET 3 LIMIT 2 /* alternative keyword */ </pre>
<p>When the FETCH keyword is used, the specified number of rows must
      be at least 1, otherwise an error is returned. This behaviour is
      consistent with the SQL Standard. When the LIMIT keyword is used, the
      specified number of rows can be zero, which means return all rows (no
      LIMIT). In MySQL and PostgreSQL syntax modes, zero limit means no rows
      (empty result).</p>
<p>If there is an index on all the columns specified in the ORDER BY
      clause, it is normally used for slicing. In some queries, an index on
      another column may take precedence because it is used to process the
      WHERE condition. It is possible to add <code class="literal">USING INDEX</code> to
      the end of the slicing clause to force the use of the index for ordering
      and slicing, instead of the index for the WHERE condition.</p>
</div>
</div>
<div class="section" title="Data Change Statements">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="dac_data_change_statements"></a>Data Change Statements</h2>
</div>
</div>
</div>
<div class="section" title="Delete Statement">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_delete_statement"></a>Delete Statement</h3>
</div>
</div>
</div>
<a name="N12B9E" class="indexterm"></a>
<p>
<span class="bold"><strong>DELETE FROM</strong></span>
</p>
<p>
<span class="emphasis"><em>delete statement: searched</em></span>
</p>
<p>
<code class="literal">&lt;delete statement: searched&gt; ::= DELETE FROM
      &lt;target table&gt; [ [ AS ] &lt;correlation name&gt; ] [ WHERE
      &lt;search condition&gt; ]</code>
</p>
<p>Delete rows of a table. The search condition is a
      <code class="literal">&lt;boolean value expression&gt;</code> that is evaluated
      for each row of the table. If the condition is true, the row is deleted.
      If the condition is not specified, all the rows of the table are
      deleted. In fact, an implicit SELECT is performed in the form of
      <code class="literal">SELECT * FROM &lt;target table&gt; [ WHERE &lt;search
      condition&gt;]</code> and the selected rows are deleted. When used in
      JDBC, the number of rows returned by the implicit SELECT is returned as
      the update count.</p>
<p>If there are FOREIGN KEY constraints on other tables that
      reference the subject table, and the FOREIGN KEY constraints have
      referential actions, then rows from those other tables that reference
      the deleted rows are either deleted, or updated, according to the
      specified referential actions.</p>
<p>In the second example below the rows that have the maximum
      value for column A are deleted;</p>
<pre class="programlisting"> DELETE FROM T WHERE C &gt; 5
 DELETE FROM T AS TT WHERE TT.A = (SELECT MAX(A) FROM T)
</pre>
</div>
<div class="section" title="Truncate Statement">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_truncate_statement"></a>Truncate Statement</h3>
</div>
</div>
</div>
<a name="N12BBF" class="indexterm"></a>
<p>
<span class="bold"><strong>TRUNCATE TABLE</strong></span>
</p>
<p>
<span class="emphasis"><em>truncate table statement</em></span>
</p>
<p>
<code class="literal">&lt;truncate table statement&gt; ::= TRUNCATE TABLE
      &lt;target table&gt; [ &lt;identity column restart option&gt; ] [
      &lt;truncate options&gt; ]</code>
</p>
<p>
<code class="literal">&lt;identity column restart option&gt; ::= CONTINUE
      IDENTITY | RESTART IDENTITY</code>
</p>
<p>
<code class="literal">&lt;truncate options&gt; ::= AND COMMIT [ NO CHECK
      ]</code>
</p>
<p>Delete all rows of a table without firing its triggers. This
      statement can only be used on base tables (not views). If the table is
      referenced in a FOREIGN KEY constraint defined on another table, the
      statement causes an exception. Triggers defined on the table are not
      executed with this statement. The default for <code class="literal">&lt;identity
      column restart option&gt;</code> is <code class="literal">CONTINUE
      IDENTITY</code>. This means no change to the IDENTITY sequence of the
      table. If <code class="literal">RESTART IDENTITY</code> is specified, then the
      sequence is reset to its start value.</p>
<p>TRUNCATE is faster than ordinary DELETE. The TRUNCATE statement
      is an SQL Standard data change statement, therefore it is performed
      under transaction control and can be rolled back if the connection is
      not in the auto-commit mode.</p>
<p>HyperSQL also supports the optional AND COMMIT and NO CHECK
      options. If AND COMMIT is used, then the transaction is committed with
      the execution of the TRUNCATE statement. The action cannot be rolled
      back. If the additional NO CHECK option is also specified, then the
      TRUNCATE statement is executed even if the table is referenced in a
      FOREIGN KEY constraint defined on another, non-empty table. This form of
      TRUNCATE is faster than the default form and does not use much
      memory.</p>
<a name="N12BE3" class="indexterm"></a>
<p>
<span class="bold"><strong>TRUNCATE SCHEMA</strong></span>
</p>
<p>
<span class="emphasis"><em>truncate schema statement</em></span>
</p>
<p>
<code class="literal">&lt;truncate schema statement&gt; ::= TRUNCATE SCHEMA
      &lt;target schema&gt; [ &lt;identity column restart option&gt; ] AND
      COMMIT [ NO CHECK ]</code>
</p>
<p>Performs the equivalent of a TRUNCATE TABLE ... AND COMMIT on
      all the table in the schema. If the additional NO CHECK option is also
      specified, then the TRUNCATE statement is executed even if any of the
      tables in the schema is referenced in a FOREIGN KEY constraint defined
      on a non-empty table in a different schema.</p>
<p>If RESTART IDENTITY is specified, all table IDENTITY sequences
      and all SEQUENCE objects in the schema are reset to their start
      values.</p>
<p>Use of this statement requires schema ownership or
      administrative privileges.</p>
</div>
<div class="section" title="Insert Statement">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_insert_statement"></a>Insert Statement</h3>
</div>
</div>
</div>
<a name="N12BFC" class="indexterm"></a>
<p>
<span class="bold"><strong>INSERT INTO</strong></span>
</p>
<p>
<span class="emphasis"><em>insert statement</em></span>
</p>
<p>
<code class="literal">&lt;insert statement&gt; ::= INSERT INTO &lt;target
      table&gt; &lt;insert columns and source&gt;</code>
</p>
<p>
<code class="literal">&lt;insert columns and source&gt; ::= &lt;from
      subquery&gt; | &lt;from constructor&gt; | &lt;from
      default&gt;</code>
</p>
<p>
<code class="literal">&lt;from subquery&gt; ::= [ &lt;left paren&gt;
      &lt;insert column list&gt; &lt;right paren&gt; ] [ &lt;override
      clause&gt; ] &lt;query expression&gt;</code>
</p>
<p>
<code class="literal">&lt;from constructor&gt; ::= [ &lt;left paren&gt;
      &lt;insert column list&gt; &lt;right paren&gt; ] [ &lt;override
      clause&gt; ] &lt;contextually typed table value
      constructor&gt;</code>
</p>
<p>
<code class="literal">&lt;override clause&gt; ::= OVERRIDING USER VALUE |
      OVERRIDING SYSTEM VALUE</code>
</p>
<p>
<code class="literal">&lt;from default&gt; ::= DEFAULT
      VALUES</code>
</p>
<p>
<code class="literal">&lt;insert column list&gt; ::= &lt;column name
      list&gt;</code>
</p>
<p>Insert new rows in a table. An INSERT statement inserts one or
      more rows into the table.</p>
<p>The special form, <code class="literal">INSERT INTO &lt;target table&gt;
      DEFAULT VALUES</code> can be used with tables which have a default
      value for each column.</p>
<p>With the other forms of INSERT, the optional
      <code class="literal">(&lt;insert column list&gt;)</code> specifies to which
      columns of the table the new values are assigned.</p>
<p>In one form, the inserted values are from a <code class="literal">&lt;query
      expression&gt;</code> and all the rows that are returned by the
      <code class="literal">&lt;query expression&gt;</code> are inserted into the table.
      If the <code class="literal">&lt;query expression&gt;</code> returns no rows,
      nothing is inserted.</p>
<p>In the other form, a comma separated list of values called
      <code class="literal">&lt;contextually typed table value constructor&gt;</code> is
      used to insert one or more rows into the table. This list is
      contextually typed, because the keywords NULL and DEFAULT can be used
      for the values that are assigned to each column of the table. The
      keyword DEFAULT means the default value of the column and can be used
      only if the target column has a default value or is an IDENTITY or
      GENERATED column of the table.</p>
<p>The <code class="literal">&lt;override clause&gt;</code> must be used
      when a value is explicitly assigned to a column that has been defined as
      GENERATED ALWAYS AS IDENTITY. The clause, OVERRIDE SYSTEM VALUE means
      the provided values are used for the insert, while OVERRIDING USER VALUE
      means the provided values are simply ignored and the values generated by
      the system are used instead.</p>
<p>An array can be inserted into a column of the array type by
      using literals, by specifying a parameter in a prepared statement or an
      existing array returned by query expression. The last example below
      inserts an array.</p>
<p>The rows that are inserted into the table are checked against
      all the constraints that have been declared on the table. The whole
      INSERT operation fails if any row fails to inserted due to constraint
      violation. Examples:</p>
<pre class="programlisting"> CREATE TABLE T (A INTEGER GENERATED BY DEFAULT AS IDENTITY, B INTEGER DEFAULT 2)
 INSERT INTO T DEFAULT VALUES /* all columns of T have DEFAULT clauses */
 INSERT INTO T (SELECT * FROM Z) /* table Z has the same columns as table T */
 INSERT INTO T (A,B) VALUES ((1,2),(3,NULL), (DEFAULT,6)) /* three rows are inserted into table T */
 ALTER TABLE T ADD COLUMN D VARCHAR(10) ARRAY /* an ARRAY column is added */
 INSERT INTO T VALUES DEFAULT, 3, ARRAY['hot','cold']
</pre>
<p>If the table contains an IDENTITY column, the value for this
      column for the last row inserted by a session can be retrieved using a
      call to the IDENTITY() function. This call returns the last value
      inserted by the calling session. When the insert statement is executed
      with a JDBC Statement or PreparedStatement method, the
      getGeneratedKeys() method of Statement can be used to retrieve not only
      the IDENTITY column, but also any GENERATED computed column, or any
      other column. The getGeneratedKeys() returns a ResultSet with one or
      more columns. This contains one row per inserted row, and can therefore
      return all the generated columns for a multi-row insert.</p>
<p>There are three methods of specifying which generated keys should
      be returned. The first method does not specify the columns of the table.
      With this method, the returned ResultSet will have a column for each
      column of the table that is defined as GENERATED ... AS IDENTITY or
      GENERATED ... AS (&lt;expression&gt;). The two other methods require the
      user to specify which columns should be returned, either by column
      indexes, or by column names. With these methods, there is no restriction
      on which columns of the inserted values to be returned. This is
      especially useful when some columns have a default clause which is a
      function, or when there are BEFORE triggers on the table that may
      provide the inserted value for some of the columns.</p>
</div>
<div class="section" title="Update Statement">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_update_statement"></a>Update Statement</h3>
</div>
</div>
</div>
<a name="N12C4C" class="indexterm"></a>
<p>
<span class="bold"><strong>UPDATE</strong></span>
</p>
<p>
<span class="emphasis"><em>update statement: searched</em></span>
</p>
<p>
<code class="literal">&lt;update statement: searched&gt; ::= UPDATE
      &lt;target table&gt; [ [ AS ] &lt;correlation name&gt; ] SET &lt;set
      clause list&gt; [ WHERE &lt;search condition&gt; ]</code>
</p>
<p>Update rows of a table. An UPDATE statement selects rows from
      the <code class="literal">&lt;target table&gt;</code> using an implicit SELECT
      statement formed in the following manner:</p>
<p>
<code class="literal">SELECT * FROM &lt;target table&gt; [ [ AS ]
      &lt;correlation name&gt; ] [ WHERE &lt;search condition&gt;
      ]</code>
</p>
<p>Then it applies the <code class="literal">SET &lt;set clause
      list&gt;</code> expression to each selected row.</p>
<p>If the implicit SELECT returns no rows, no update takes place.
      When used in JDBC, the number of rows returned by the implicit SELECT is
      returned as the update count.</p>
<p>If there are FOREIGN KEY constraints on other tables that
      reference the subject table, and the FOREIGN KEY constraints have
      referential actions, then rows from those other tables that reference
      the updated rows are updated, according to the specified referential
      actions.</p>
<p>The rows that are updated are checked against all the
      constraints that have been declared on the table. The whole UPDATE
      operation fails if any row violates any constraint.</p>
<a name="N12C6E" class="indexterm"></a>
<p>
<span class="bold"><strong>set clause list</strong></span>
</p>
<p>
<span class="emphasis"><em>set clause list</em></span>
</p>
<p>
<code class="literal">&lt;set clause list&gt; ::= &lt;set clause&gt; [ {
      &lt;comma&gt; &lt;set clause&gt; }... ]</code>
</p>
<p>
<code class="literal">&lt;set clause&gt; ::= &lt;multiple column
      assignment&gt; | &lt;set target&gt; &lt;equals operator&gt; &lt;update
      source&gt;</code>
</p>
<p>
<code class="literal">&lt;multiple column assignment&gt; ::= &lt;set target
      list&gt; &lt;equals operator&gt; &lt;assigned
      row&gt;</code>
</p>
<p>
<code class="literal">&lt;set target list&gt; ::= &lt;left paren&gt; &lt;set
      target&gt; [ { &lt;comma&gt; &lt;set target&gt; }... ] &lt;right
      paren&gt;</code>
</p>
<p>
<code class="literal">&lt;assigned row&gt; ::= &lt;contextually typed row
      value expression&gt;</code>
</p>
<p>
<code class="literal">&lt;set target&gt; ::= &lt;column
      name&gt;</code>
</p>
<p>
<code class="literal">&lt;update source&gt; ::= &lt;value expression&gt; |
      &lt;contextually typed value specification&gt;</code>
</p>
<p>Specify a list of assignments. This is used in UPDATE, MERGE
      and SET statements to assign values to a scalar or row target.</p>
<p>Apart from setting a whole target to a value, a SET statement
      can set individual elements of an array to new values. The last example
      below shows this form of assignment to the array in the column named
      B.</p>
<p>In the examples given below, UPDATE statements with single and
      multiple assignments are shown. Note in the third example, a SELECT
      statement is used to provide the update values for columns A and C,
      while the update value for column B is given separately. The SELECT
      statement must return exactly one row . In this example the SELECT
      statement refers to the existing value for column C in its search
      condition.</p>
<pre class="programlisting"> UPDATE T SET A = 5 WHERE ...
 UPDATE T SET (A, B) = (1, NULL) WHERE ...
 UPDATE T SET (A, C) = (SELECT X, Y FROM U WHERE Z = C), B = 10 WHERE ...
 UPDATE T SET A = 3, B[3] = 'warm'
</pre>
</div>
<div class="section" title="Merge Statement">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dac_merge_statement"></a>Merge Statement</h3>
</div>
</div>
</div>
<a name="N12C9B" class="indexterm"></a>
<p>
<span class="bold"><strong>MERGE INTO</strong></span>
</p>
<p>
<span class="emphasis"><em>merge statement</em></span>
</p>
<p>
<code class="literal">&lt;merge statement&gt; ::= MERGE INTO &lt;target
      table&gt; [ [ AS ] &lt;merge correlation name&gt; ] USING &lt;table
      reference&gt; ON &lt;search condition&gt; &lt;merge operation
      specification&gt;</code>
</p>
<p>
<code class="literal">&lt;merge correlation name&gt; ::= &lt;correlation
      name&gt;</code>
</p>
<p>
<code class="literal">&lt;merge operation specification&gt; ::= &lt;merge
      when clause&gt;...</code>
</p>
<p>
<code class="literal">&lt;merge when clause&gt; ::= &lt;merge when matched
      clause&gt; | &lt;merge when not matched clause&gt;</code>
</p>
<p>
<code class="literal">&lt;merge when matched clause&gt; ::= WHEN MATCHED
      THEN &lt;merge update specification&gt;</code>
</p>
<p>
<code class="literal">&lt;merge when not matched clause&gt; ::= WHEN NOT
      MATCHED THEN &lt;merge insert specification&gt;</code>
</p>
<p>
<code class="literal">&lt;merge update specification&gt; ::= UPDATE SET
      &lt;set clause list&gt;</code>
</p>
<p>
<code class="literal">&lt;merge insert specification&gt; ::= INSERT [
      &lt;left paren&gt; &lt;insert column list&gt; &lt;right paren&gt; ] [
      &lt;override clause&gt; ] VALUES &lt;merge insert value
      list&gt;</code>
</p>
<p>
<code class="literal">&lt;merge insert value list&gt; ::= &lt;left paren&gt;
      &lt;merge insert value element&gt; [ { &lt;comma&gt; &lt;merge insert
      value element&gt; }... ] &lt;right paren&gt;</code>
</p>
<p>
<code class="literal">&lt;merge insert value element&gt; ::= &lt;value
      expression&gt; | &lt;contextually typed value
      specification&gt;</code>
</p>
<p>Update rows, or insert new rows into the <code class="literal">&lt;target
      table&gt;</code>. The MERGE statement uses a second table, specified
      by <code class="literal">&lt;table reference&gt;</code>, to determine the rows to
      be updated or inserted. It is possible to use the statement only to
      update rows or to insert rows, but usually both update and insert are
      specified.</p>
<p>The <code class="literal">&lt;search condition&gt;</code> matches each
      row of the <code class="literal">&lt;table reference&gt;</code> with each row of
      the <code class="literal">&lt;target table&gt;</code>. If the two rows match then
      the UPDATE clause is used to update the matching row of the target
      table. Those rows of <code class="literal">&lt;table reference&gt;</code> that
      have no matching rows are then used to insert new rows into the
      <code class="literal">&lt;target table&gt;</code>. Therefore, a MERGE statement
      can update between 0 and all the rows of the <code class="literal">&lt;target
      table&gt;</code> and can insert between 0 and the number of the rows
      in <code class="literal">&lt;table reference&gt;</code> into the
      <code class="literal">&lt;target table&gt;</code>. If any row in the
      <code class="literal">&lt;target table&gt;</code> matches more than one row in
      <code class="literal">&lt;table reference&gt;</code> a cardinality error is
      raised. On the other hand, several rows in the <code class="literal">&lt;target
      table&gt;</code> can match a single row in <code class="literal">&lt;table
      reference&gt;</code> without any error. The constraints and
      referential actions specified on the database tables are enforced the
      same way as for an update and an insert statement.</p>
<p>The MERGE statement can be used with only the WHEN NOT MATCHED
      clause as a conditional INSERT statement that inserts a row if no
      existing rows match a condition.</p>
<p>In the first example below, the table originally contains two
      rows for different furniture. The <code class="literal">&lt;table
      reference&gt;</code> is the <code class="literal">(VALUES(1, 'conference table'),
      (14, 'sofa'), (5, 'coffee table'))</code> expression, which evaluates
      to a table with 3 rows. When the x value for a row matches an existing
      row, then the existing row is updated. When the x value does not match,
      the row is inserted. Therefore one row of table t is updated from
      'dining table' to 'conference table', and two rows are inserted into
      table t. The second example uses a SELECT statement as the source of the
      values for the MERGE.</p>
<p>In the third example, a new row in inserted into the table only
      when the primary key for the new row does not exist. This example uses
      parameters and should be executed as a JDBC PreparedStatement. The
      parameter is cast as INTEGER because the MERGE statement does not use
      determine the types of values in the USING clause.</p>
<pre class="programlisting"> CREATE TABLE t (id INT PRIMARY KEY, description VARCHAR(100))
 INSERT INTO t VALUES (1, 'dining table'), (2, 'deck chair')

 MERGE INTO t USING (VALUES(1, 'conference table'), (14, 'sofa'), (5, 'coffee table')) 
   AS vals(x,y) ON t.id = vals.x
   WHEN MATCHED THEN UPDATE SET t.description = vals.y
   WHEN NOT MATCHED THEN INSERT VALUES vals.x, vals.y

 MERGE INTO t USING (SELECT * FROM tt WHERE acol = 2) AS vals(x,y) ON t.id = vals.x
   WHEN MATCHED THEN UPDATE SET t.description = vals.y
   WHEN NOT MATCHED THEN INSERT VALUES vals.x, vals.y

 MERGE INTO t USING (VALUES(CAST(? AS INT))) AS vals(x) ON t.id = vals.x
   WHEN NOT MATCHED THEN INSERT VALUES vals.x, ?
</pre>
</div>
</div>
<div class="section" title="Diagnostics and State">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="dac_diagnostics_state"></a>Diagnostics and State</h2>
</div>
</div>
</div>
<p>HyperSQL supports some SQL statements, expressions, functions and
    Java methods that report on the most recently executed statement.</p>
<p>The <code class="literal">IDENTITY()</code> function returns the last inserted
    identity value for the current session.</p>
<p>The <code class="literal">GET DIAGNOSTICS</code> statement is supported to a
    limited extent. The built-in function <code class="literal">DIAGNOSTICS()</code> is
    an alternative. These are normally used in SQL/PSM routines to check the
    result of the last data update operation.</p>
<a name="N12D14" class="indexterm"></a>
<p>
<span class="bold"><strong>GET DIAGNOSTICS</strong></span>
</p>
<p>
<span class="emphasis"><em>get diagnostics statement</em></span>
</p>
<p>
<code class="literal">&lt;get diagnostics statement&gt; ::= GET DIAGNOSTICS
    &lt;simple target value specification&gt; = ROW_COUNT</code>
</p>
<p>The <code class="literal">&lt;simple target value specification&gt;</code> is
    a session variable, or a routine variable or OUT parameter.</p>
<p>The keyword <code class="literal">ROW_COUNT</code> specifies the row count
    returned by the last executed statement. For INSERT, UPDATE, DELETE and
    MERGE statements, this is the number of rows affected by the statement.
    This is the same value as returned by JDBC
    <code class="literal">executeUpdate()</code> methods. For all other statements, zero
    is returned.</p>
<p>The value of <code class="literal">ROW_COUNT</code> is stored in the specified
    target.</p>
<p>In future versions, more options will be supported for diagnostics
    values.</p>
</div>
</div>
<div class="chapter" title="Chapter&nbsp;8.&nbsp;SQL-Invoked Routines">
<div class="titlepage">
<div>
<div>
<h2 class="title">
<a name="sqlroutines-chapt"></a>Chapter&nbsp;8.&nbsp;SQL-Invoked Routines</h2>
</div>
<div>
<div class="authorgroup">
<div class="author">
<h3 class="author">
<span class="firstname">Fred</span> <span class="surname">Toussi</span>
</h3>
<div class="affiliation">
<span class="orgname">The HSQL Development Group<br>
</span>
</div>
</div>
</div>
</div>
<div>
<p class="releaseinfo">$Revision: 5271 $</p>
</div>
<div>
<div class="legalnotice" title="Legal Notice">
<a name="N12D5B"></a>
<p>Copyright 2010-2012 Fred Toussi. Permission is granted to
      distribute this document without any alteration under the terms of the
      HSQLDB license. Additional permission is granted to the HSQL Development
      Group to distribute this document with or without alterations under the
      terms of the HSQLDB license.</p>
</div>
</div>
<div>
<p class="pubdate">2014-02-13 18:21:41-0500</p>
</div>
</div>
</div>
<div class="toc">
<p>
<b>Table of Contents</b>
</p>
<dl>
<dt>
<span class="section"><a href="#src_routine_definition">Routine Definition</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#src_routine_characteristics">Routine Characteristics</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#src_psm_routines">SQL Language Routines (PSM)</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#src_advantages">Advantages and Disadvantages</a></span>
</dt>
<dt>
<span class="section"><a href="#src_psm_statements">Routine Statements</a></span>
</dt>
<dt>
<span class="section"><a href="#src_psm_compound">Compound Statement</a></span>
</dt>
<dt>
<span class="section"><a href="#src_psm_table_vars">Table Variables</a></span>
</dt>
<dt>
<span class="section"><a href="#src_psm_vars">Variables</a></span>
</dt>
<dt>
<span class="section"><a href="#src_psm_cursors">Cursors</a></span>
</dt>
<dt>
<span class="section"><a href="#src_psm_handlers">Handlers</a></span>
</dt>
<dt>
<span class="section"><a href="#src_psm_assignment">Assignment Statement</a></span>
</dt>
<dt>
<span class="section"><a href="#src_psm_select_single">Select Statement : Single Row</a></span>
</dt>
<dt>
<span class="section"><a href="#src_formal_parameters">Formal Parameters</a></span>
</dt>
<dt>
<span class="section"><a href="#src_psm_iterated_statements">Iterated Statements</a></span>
</dt>
<dt>
<span class="section"><a href="#src_psm_for_statement">Iterated FOR Statement</a></span>
</dt>
<dt>
<span class="section"><a href="#src_psm_conditional">Conditional Statements</a></span>
</dt>
<dt>
<span class="section"><a href="#src_psm_return_statement">Return Statement</a></span>
</dt>
<dt>
<span class="section"><a href="#src_psm_control_statements">Control Statements</a></span>
</dt>
<dt>
<span class="section"><a href="#src_psm_exceptions">Raising Exceptions</a></span>
</dt>
<dt>
<span class="section"><a href="#src_routine_polymorphism">Routine Polymorphism</a></span>
</dt>
<dt>
<span class="section"><a href="#src_returning_data">Returning Data From Procedures</a></span>
</dt>
<dt>
<span class="section"><a href="#src_psm_recursive_routines">Recursive Routines</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#src_jrt_routines">Java Language Routines (SQL/JRT)</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#src_jrt_polymorphis">Polymorphism</a></span>
</dt>
<dt>
<span class="section"><a href="#src_jrt_procedures">Java Language Procedures</a></span>
</dt>
<dt>
<span class="section"><a href="#src_jrt_static_methods">Java Static Methods</a></span>
</dt>
<dt>
<span class="section"><a href="#src_jrt_legacy">Legacy Support</a></span>
</dt>
<dt>
<span class="section"><a href="#src_jrt_access_control">Securing Access to Classes</a></span>
</dt>
<dt>
<span class="section"><a href="#N133A3">Warning</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#src_aggregate_functions">User Defined Aggregate Functions</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#src_aggregate_function_definition">Definition of Aggregate Functions</a></span>
</dt>
<dt>
<span class="section"><a href="#src_psm_aggregate_functions">SQL PSM Aggregate Functions</a></span>
</dt>
<dt>
<span class="section"><a href="#src_jrt_aggregate_functions">Java Aggregate Functions</a></span>
</dt>
</dl>
</dd>
</dl>
</div>
<p>SQL-invoked routines are functions and procedures called from SQL.
  HyperSQL 2.0 supports routines conforming to two parts of the SQL Standard.
  Routines written in the SQL language are supported in conformance to SQL/PSM
  (Persistent Stored Modules) specification. Routines written in Java are
  supported in broad conformance to SQL/JRT specification. In addition,
  HyperSQL's previous non-standard support for calling Java routines without
  prior method definition is retained and enhanced in the latest version by
  extending the SQL/JRT specification.</p>
<p>HyperSQL also supports user defined aggregate functions written in the
  SQL language or Java. This feature is an extension to the SQL
  Standard.</p>
<p>SQL-invoked routines are schema objects. Naming and referencing
  follows conventions common to all schema objects. The same routine name can
  be defined in two different schemas and used with schema-qualified
  references.</p>
<p>A routine is either a procedure or a function.</p>
<p>A function:</p>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>is defined with CREATE FUNCTION</p>
</li>
<li class="listitem">
<p>always returns a single value or a single table</p>
</li>
<li class="listitem">
<p>does not modify the data in the database</p>
</li>
<li class="listitem">
<p>is used as part of an SQL statement</p>
</li>
<li class="listitem">
<p>can have parameters</p>
</li>
<li class="listitem">
<p>can be polymorphic</p>
</li>
</ul>
</div>
<p>A procedure:</p>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>is defined with CREATE PROCEDURE</p>
</li>
<li class="listitem">
<p>can return zero to multiple values or result sets</p>
</li>
<li class="listitem">
<p>can modify the data in the database</p>
</li>
<li class="listitem">
<p>is called separately, using the CALL statement</p>
</li>
<li class="listitem">
<p>can have parameters</p>
</li>
<li class="listitem">
<p>can be polymorphic</p>
</li>
</ul>
</div>
<p>Definition of routine signature and characteristics, name resolution
  and invocation are all implemented uniformly for routines written in SQL or
  Java.</p>
<div class="section" title="Routine Definition">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="src_routine_definition"></a>Routine Definition</h2>
</div>
</div>
</div>
<p>SQL-Invoked Routines, whether PSM or JRT, are defined using a SQL
    statement with the same syntax. The part that is different is the
    &lt;routine body&gt; which consists of SQL statements in PSM routines or a
    reference to a Java method in JRT routines.</p>
<p>Details of Routine definition are discussed in this section. You may
    start by reading the next two sections which provide several examples
    before reading this section for the details.</p>
<p>Routine definition has several mandatory or optional clauses. The
    complete BNF supported by HyperSQL and the remaining clauses are
    documented in this section.</p>
<a name="N12D9C" class="indexterm"></a>
<p>
<span class="bold"><strong>CREATE FUNCTION</strong></span>
</p>
<a name="N12DA5" class="indexterm"></a>
<p>
<span class="bold"><strong>CREATE PROCEDURE</strong></span>
</p>
<p>
<span class="emphasis"><em>routine definition</em></span>
</p>
<p>Routine definition is similar for procedures and functions. A
    function definition has the mandatory <code class="literal">&lt;returns
    clause&gt;</code> which is discussed later. The description given so
    far covers the essential elements of the specification with the BNF given
    below.</p>
<p>
<code class="literal">&lt;schema procedure&gt; ::= CREATE PROCEDURE &lt;schema
    qualified routine name&gt; &lt;SQL parameter declaration list&gt;
    &lt;routine characteristics&gt; &lt;routine body&gt;</code>
</p>
<p>
<code class="literal">&lt;schema function&gt; ::= CREATE FUNCTION &lt;schema
    qualified routine name&gt; &lt;SQL parameter declaration list&gt;
    &lt;returns clause&gt; &lt;routine characteristics&gt; &lt;routine
    body&gt;</code>
</p>
<p>Parameter declaration list has been described above. For SQL/JRT
    routines, the <code class="literal">&lt;SQL parameter name&gt;</code> is optional
    while for SQL/PSM routines, it is required. If the <code class="literal">&lt;parameter
    mode&gt;</code> of a parameter is OUT or INOUT, it must be specified.
    The BNF is given below:</p>
<p>
<code class="literal">&lt;SQL parameter declaration list&gt; ::= &lt;left
    paren&gt; [ &lt;SQL parameter declaration&gt; [ { &lt;comma&gt; &lt;SQL
    parameter declaration&gt; }... ] ] &lt;right paren&gt;</code>
</p>
<p>
<code class="literal">&lt;SQL parameter declaration&gt; ::= [ &lt;parameter
    mode&gt; ] [ &lt;SQL parameter name&gt; ] &lt;parameter
    type&gt;</code>
</p>
<p>
<code class="literal">&lt;parameter mode&gt; ::= IN | OUT |
    INOUT</code>
</p>
<p>
<code class="literal">&lt;parameter type&gt; ::= &lt;data
    type&gt;</code>
</p>
<p>Return Value and Table Functions</p>
<a name="N12DD2" class="indexterm"></a>
<p>
<span class="bold"><strong>RETURNS</strong></span>
</p>
<p>
<span class="emphasis"><em>returns clause</em></span>
</p>
<p>The <code class="literal">&lt;returns clause&gt;</code> specifies the type of
    the return value of a function (not a procedure). For all SQL/PSM
    functions and ordinary SQL/JRT functions, this is simply a type definition
    which can be a built-in type, a DOMAIN type or a DISTINCT type, or
    alternatively, a TABLE definition. For example, RETURNS INTEGER.</p>
<p>For a SQL/JRT function, it is possible to define a
    <code class="literal">&lt;returns table type&gt;</code> for a Java method that
    returns a <code class="classname">java.sql.ResultSet</code> object. Such SQL/JRT
    functions are called <em class="glossterm">table functions</em>. Table
    functions are used differently from normal functions. A table function can
    be used in an SQL query expression exactly where a normal table or view is
    allowed. At the time of invocation, the Java method is called and the
    returned ResultSet is transformed into an SQL table. The column types of
    the declared TABLE must match those of the ResultSet, otherwise an
    exception is raised at the time of invocation.</p>
<p>If a <code class="literal">&lt;returns table type&gt;</code> is defined for an
    SQL/PSM function, the following expression is used inside the function to
    return a table: <code class="literal">RETURN TABLE ( &lt;query expression&gt;
    );</code> In the example blow, a table with two columns is
    returned.</p>
<pre class="programlisting"> RETURN TABLE ( SELECT a, b FROM atable WHERE e = 10 );</pre>
<p>Functions that return a table are designed to be used in SELECT
    statements using the TABLE keyword to form a joined table.</p>
<p>When a JDBC <code class="literal">CallableStatement</code> is used to CALL the
    function, the table returned from the function call is returned and can be
    accessed with the <code class="literal">getResultSet()</code> method of the
    <code class="literal">CallableStatement</code>.</p>
<p>
<code class="literal">&lt;returns clause&gt; ::= RETURNS &lt;returns
    type&gt;</code>
</p>
<p>
<code class="literal">&lt;returns type&gt; ::= &lt;returns data type&gt; |
    &lt;returns table type&gt;</code>
</p>
<p>
<code class="literal">&lt;returns table type&gt; ::= TABLE &lt;table function
    column list&gt;</code>
</p>
<p>
<code class="literal">&lt;table function column list&gt; ::= &lt;left
    paren&gt; &lt;table function column list element&gt; [ { &lt;comma&gt;
    &lt;table function column list element&gt; } ... ] &lt;right
    paren&gt;</code>
</p>
<p>
<code class="literal">&lt;table function column list element&gt; ::=
    &lt;column name&gt; &lt;data type&gt;</code>
</p>
<p>
<code class="literal">&lt;returns data type&gt; ::= &lt;data
    type&gt;</code>
</p>
<a name="N12E17" class="indexterm"></a>
<p>
<span class="bold"><strong>routine body</strong></span>
</p>
<p>
<span class="emphasis"><em>routine body</em></span>
</p>
<p>Routine body is either one or more SQL statements or a Java
    reference. The user that defines the routine by issuing the CREATE
    FUNCTION or CREATE SCHEMA command must have the relevant access rights to
    all tables, sequences, routines, etc. that are accessed by the routine. If
    another user is given EXECUTE privilege on the routine, then there are two
    possibilities, depending on the <code class="literal">&lt;rights clause&gt;</code>.
    This clause refers to the access rights that are checked when a routine is
    invoked. The default is <code class="literal">SQL SECURITY DEFINER</code>, which
    means access rights of the definer are used; therefore no extra checks are
    performed when the other user invokes the routine. The alternative
    <code class="literal">SQL SECURITY INVOKER</code> means access rights on all the
    database objects referenced by the routine are checked for the invoker.
    This alternative is not supported by HyperSQL.</p>
<p>
<code class="literal">&lt;routine body&gt; ::= &lt;SQL routine spec&gt; |
    &lt;external body reference&gt;</code>
</p>
<p>
<code class="literal">&lt;SQL routine spec&gt; ::= [ &lt;rights clause&gt; ]
    &lt;SQL routine body&gt;</code>
</p>
<p>
<code class="literal">&lt;rights clause&gt; ::= SQL SECURITY INVOKER | SQL
    SECURITY DEFINER</code>
</p>
<a name="N12E37" class="indexterm"></a>
<p>
<span class="bold"><strong>SQL routine body</strong></span>
</p>
<p>
<span class="emphasis"><em>SQL routine body</em></span>
</p>
<p>The routine body of a an SQL routine consists of an
    statement.</p>
<p>
<code class="literal">&lt;SQL routine body&gt; ::= &lt;SQL procedure
    statement&gt;</code>
</p>
<a name="N12E48" class="indexterm"></a>
<p>
<span class="bold"><strong>EXTERNAL NAME</strong></span>
</p>
<p>
<span class="emphasis"><em>external body reference</em></span>
</p>
<p>External name specifies the qualified name of the Java method
    associated with this routine. Early releases of HyperSQL 2.0 only supports
    Java methods within the classpath. The <code class="literal">&lt;external Java
    reference string&gt;</code> is a quoted string which starts with
    CLASSPATH: and is followed by the Java package, class and method names
    separated with dots. HyperSQL does not currently support the optional
    <code class="literal">&lt;Java parameter declaration list&gt;</code>.</p>
<p>
<code class="literal">&lt;external body reference&gt; ::= EXTERNAL NAME
    &lt;external Java reference string&gt;</code>
</p>
<p>
<code class="literal">&lt;external Java reference string&gt; ::= &lt;jar and
    class name&gt; &lt;period&gt; &lt;Java method name&gt; [ &lt;Java
    parameter declaration list&gt; ]</code>
</p>
<div class="section" title="Routine Characteristics">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="src_routine_characteristics"></a>Routine Characteristics</h3>
</div>
</div>
</div>
<p>The <code class="literal">&lt;routine characteristics&gt;</code> clause
      covers several sub-clauses</p>
<p>
<code class="literal">&lt;routine characteristics&gt; ::= [ &lt;routine
      characteristic&gt;... ]</code>
</p>
<p>
<code class="literal">&lt;routine characteristic&gt; ::= &lt;language
      clause&gt; | &lt;parameter style clause&gt; | SPECIFIC &lt;specific
      name&gt; | &lt;deterministic characteristic&gt; | &lt;SQL-data access
      indication&gt; | &lt;null-call clause&gt; | &lt;returned result sets
      characteristic&gt; | &lt;savepoint level
      indication&gt;</code>
</p>
<a name="N12E71" class="indexterm"></a>
<p>
<span class="bold"><strong>LANGUAGE</strong></span>
</p>
<p>
<span class="emphasis"><em>language clause</em></span>
</p>
<p>The <code class="literal">&lt;language clause&gt;</code> refers to the
      language in which the routine body is written. It is either SQL or Java.
      The default is SQL, so JAVA must be specified for SQL/JRT
      routines.</p>
<p>
<code class="literal">&lt;language clause&gt; ::= LANGUAGE &lt;language
      name&gt;</code>
</p>
<p>
<code class="literal">&lt;language name&gt; ::= SQL |
      JAVA</code>
</p>
<p>The parameter style is not allowed for SQL routines. It is
      optional for Java routines and, in HyperSQL, the only value allowed is
      JAVA.</p>
<p>
<code class="literal">&lt;parameter style&gt; ::= JAVA</code>
</p>
<a name="N12E8D" class="indexterm"></a>
<p>
<span class="bold"><strong>SPECIFIC NAME</strong></span>
</p>
<p>
<span class="emphasis"><em>specific name</em></span>
</p>
<p>The <code class="literal">SPECIFIC &lt;specific name&gt;</code> clause is
      optional but the engine will creates an automatic name if it is not
      present. When there are several versions of the same routine, the
      <code class="literal">&lt;specific name&gt;</code> is used in schema manipulation
      statements to drop or alter a specific version. The
      <code class="literal">&lt;specific name&gt;</code> is a user-defined name. It
      applies to both functions and procedures. In the examples below, a
      specific name is specified for each function.</p>
<pre class="programlisting"> CREATE FUNCTION an_hour_before_or_now(t TIMESTAMP)
   RETURNS TIMESTAMP
   NO SQL
   LANGUAGE JAVA PARAMETER STYLE JAVA
   SPECIFIC an_hour_before_or_now_with_timestamp
   EXTERNAL NAME 'CLASSPATH:org.npo.lib.nowLessAnHour'

 CREATE FUNCTION an_hour_before_max (e_type INT)
   RETURNS TIMESTAMP SPECIFIC an_hour_before_max_with_int
   RETURN (SELECT MAX(event_time) FROM atable WHERE event_type = e_type) - 1 HOUR

</pre>
<a name="N12EA6" class="indexterm"></a>
<p>
<span class="bold"><strong>DETERMINISTIC</strong></span>
</p>
<p>
<span class="emphasis"><em>deterministic characteristic</em></span>
</p>
<p>The <code class="literal">&lt;deterministic characteristic&gt;</code> clause
      indicates that a routine is deterministic or not. Deterministic means
      the routine does not reference random values, external variables, or
      time of invocation. The default is <code class="literal">NOT DETERMINISTIC</code>.
      It is essential to declare this characteristics correctly for an SQL/JRT
      routine, as the engine does not know the contents of the Java code,
      which could include calls to methods returning random or time sensitive
      values.</p>
<p>
<code class="literal">&lt;deterministic characteristic&gt; ::= DETERMINISTIC
      | NOT DETERMINISTIC</code>
</p>
<a name="N12EBD" class="indexterm"></a>
<p>
<span class="bold"><strong>SQL DATA access</strong></span>
</p>
<p>
<span class="emphasis"><em>SQL DATA access characteristic</em></span>
</p>
<p>The <code class="literal">&lt;SQL-data access indication&gt;</code> &nbsp;clause
      indicates the extent to which a routine interacts with the database or
      the data stored in the database tables in different schemas (SQL
      DATA).</p>
<p>NO SQL means no SQL command is issued in the routine body and can
      be used only for SQL/JRT functions.</p>
<p>
<code class="literal">CONTAINS SQL</code> means some SQL commands are used,
      but they do not read or modify the SQL data. <code class="literal">READS SQL
      DATA</code> and <code class="literal">MODIFIES SQL DATA</code> are self
      explanatory.</p>
<p>A <code class="literal">CREATE PROCEDURE</code> definition can use
      <code class="literal">MODIFIES SQL DATA</code>. This is not allowed in
      <code class="literal">CREATE FUNCTION</code>. Note that a PROCEDURE or a FUNCTION
      may have internal tables or return a table which are populated by the
      routine's statements. These tables are not considered SQL DATA,
      therefore there is no need to specify <code class="literal">MODIFIES SQL
      DATA</code> for such routines.</p>
<p>
<code class="literal">&lt;SQL-data access indication&gt; ::= NO SQL |
      CONTAINS SQL | READS SQL DATA | MODIFIES SQL DATA</code>
</p>
<a name="N12EEB" class="indexterm"></a>
<p>
<span class="bold"><strong>NULL INPUT</strong></span>
</p>
<p>
<span class="emphasis"><em>null call clause</em></span>
</p>
<p>Null Arguments</p>
<p>The <code class="literal">&lt;null-call clause&gt;</code> is used only for
      functions. If a function returns NULL when any of the calling arguments
      is null, then by specifying <code class="literal">RETURNS NULL ON NULL
      INPUT</code>, calls to the function are known to be redundant and do
      not take place when an argument is null. This simplifies the coding of
      the SQL/JRT Java methods and improves performance at the same
      time.</p>
<p>
<code class="literal">&lt;null-call clause&gt; ::= RETURNS NULL ON NULL
      INPUT | CALLED ON NULL INPUT</code>
</p>
<a name="N12F04" class="indexterm"></a>
<p>
<span class="bold"><strong>SAVEPOINT LEVEL</strong></span>
</p>
<p>
<span class="emphasis"><em>transaction impact</em></span>
</p>
<p>The <code class="literal">&lt;savepoint level indication&gt;</code> is used
      only for procedures and refers to the visibility of existing savepoints
      within the body of the procedure. If <code class="literal">NEW SAVEPOINT
      LEVEL</code> is specified, savepoints that have been declared prior
      to calling the procedure become invisible within the body of the
      procedure. HyperSQL&rsquo;s implementation accepts only <code class="literal">NEW SAVEPOINT
      LEVEL</code>, which must be specified.</p>
<p>
<code class="literal">&lt;savepoint level indication&gt; ::= NEW SAVEPOINT
      LEVEL | OLD SAVEPOINT LEVEL</code>
</p>
<a name="N12F1E" class="indexterm"></a>
<p>
<span class="bold"><strong>DYNAMIC RESULT SETS</strong></span>
</p>
<p>
<span class="emphasis"><em>returned result sets
      characteristic</em></span>
</p>
<p>The <code class="literal">&lt;returned result sets characteristic&gt;</code>
      is used with SQL/PSM and SQL/JRT procedures (not with functions). The
      maximum number of result sets that a procedure may return can be
      specified with the clause below. The default is zero. If you want your
      procedure to return result sets, you must specify the maximum number of
      result sets that your procedure may return. Details are discussed in the
      next sections.</p>
<p>
<code class="literal">&lt;returned result sets characteristic&gt; ::=
      DYNAMIC RESULT SETS &lt;maximum returned result
      sets&gt;</code>
</p>
</div>
</div>
<div class="section" title="SQL Language Routines (PSM)">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="src_psm_routines"></a>SQL Language Routines (PSM)</h2>
</div>
</div>
</div>
<p>The PSM (Persistent Stored Module) specification extends the SQL
    language with structures and control statements such as conditional and
    loop statements. Both SQL Function and SQL procedure bodies use the same
    syntax, with minor exceptions.</p>
<p>The routine body is a SQL statement. In its simplest form, the body
    is a single SQL statement. A simple example of a function is given
    below:</p>
<pre class="programlisting"> CREATE FUNCTION an_hour_before (t TIMESTAMP)
   RETURNS TIMESTAMP
   RETURN t - 1 HOUR

</pre>
<p>An example of the use of the function in an SQL statement is given
    below:</p>
<pre class="programlisting"> SELECT an_hour_before(event_timestamp) AS notification_timestamp, event_name FROM events;</pre>
<p>A simple example of a procedure is given below:</p>
<pre class="programlisting"> CREATE PROCEDURE new_customer(firstname VARCHAR(50), lastname VARCHAR(50))
   MODIFIES SQL DATA
   INSERT INTO CUSTOMERS VALUES (DEFAULT, firstname, lastname, CURRENT_TIMESTAMP)

</pre>
<p>The procedure inserts a row into an existing table with the
    definition given below:</p>
<pre class="programlisting"> CREATE TABLE customers(id INTEGER GENERATED BY DEFAULT AS IDENTITY, firstname VARCHAR(50), lastname VARCHAR(50), added TIMESTAMP);</pre>
<p>An example of the use of the procedure is given below:</p>
<pre class="programlisting"> CALL new_customer('JOHN', 'SMITH');</pre>
<p>The routine body is often a compound statement. A compound statement
    can contain one or more SQL statements, which can include control
    statements, as well as nested compound statements.</p>
<p>Please note carefully the use of
    <code class="literal">&lt;semicolon&gt;</code>, which is required at the end of some
    statements but not accepted at the end of others.</p>
<div class="section" title="Advantages and Disadvantages">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="src_advantages"></a>Advantages and Disadvantages</h3>
</div>
</div>
</div>
<p>SQL Language Routines (PSM) have certain advantages over Java
      Language Routines (SQL/JRT) and a couple of disadvantages.</p>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>SQL language routines (PSM) do not rely on custom Java classes
          to be present on the classpath. The databases that use them are
          therefore more portable.</p>
</li>
<li class="listitem">
<p>For a routine that accesses SQL DATA, all the SQL statements
          in an SQL routine are known and monitored by the engine. The engine
          will not allow a table, routine or sequence that is referenced in an
          SQL routine to be dropped, or its structure modified in a way that
          will break the routine execution. The engine does not keep this
          information about a Java routine.</p>
</li>
<li class="listitem">
<p>Because the statements in an SQL routine are known to the
          engine, the execution of an SQL routine locks all the database
          objects it needs to access before the actual execution. With Java
          routines, locks are obtained during execution and this may cause
          additional delays in multi threaded access to the database.</p>
</li>
<li class="listitem">
<p>For routines that do not access SQL DATA, Java routines
          (SQL/JRT) may be faster if they perform extensive
          calculations.</p>
</li>
<li class="listitem">
<p>Only Java routines can access external programs and resources
          directly.</p>
</li>
</ul>
</div>
</div>
<div class="section" title="Routine Statements">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="src_psm_statements"></a>Routine Statements</h3>
</div>
</div>
</div>
<p>The following SQL Statements can be used only in routines. These
      statements are covered in this section.</p>
<p>
<code class="literal">&lt;handler declaration&gt;</code>
</p>
<p>
<code class="literal">&lt;table variable declaration&gt;</code>
</p>
<p>
<code class="literal">&lt;variable declaration&gt;</code>
</p>
<p>
<code class="literal">&lt;declare cursor&gt;</code>
</p>
<p>
<code class="literal">&lt;assignment statement&gt;</code>
</p>
<p>
<code class="literal">&lt;compound statement&gt;</code>
</p>
<p>
<code class="literal">&lt;case statement&gt;</code>
</p>
<p>
<code class="literal">&lt;if statement&gt;</code>
</p>
<p>
<code class="literal">&lt;while statement&gt;</code>
</p>
<p>
<code class="literal">&lt;repeat statement&gt;</code>
</p>
<p>
<code class="literal">&lt;for statement&gt;</code>
</p>
<p>
<code class="literal">&lt;loop statement&gt;</code>
</p>
<p>
<code class="literal">&lt;iterate statement</code>
</p>
<p>
<code class="literal">&lt;leave statement&gt;</code>
</p>
<p>
<code class="literal">&lt;signal statement&gt;</code>
</p>
<p>
<code class="literal">&lt;resignal statement&gt;</code>
</p>
<p>
<code class="literal">&lt;return statement&gt;</code>
</p>
<p>
<code class="literal">&lt;select statement: single
      row&gt;</code>
</p>
<p>
<code class="literal">&lt;open statement&gt;</code>
</p>
<p>The following SQL Statements can be used in procedures but not in
      generally in functions (they can be used in functions only to change the
      data in a local table variable) . These statements are covered in other
      chapters of this Guide.</p>
<p>
<code class="literal">&lt;call statement&gt;</code>
</p>
<p>
<code class="literal">&lt;delete statement&gt;</code>
</p>
<p>
<code class="literal">&lt;insert statement&gt;</code>
</p>
<p>
<code class="literal">&lt;update statement&gt;</code>
</p>
<p>
<code class="literal">&lt;merge statement&gt;</code>
</p>
<p>As shown in the examples below, the formal parameters and the
      variables of the routine can be used in statements, similar to the way a
      column reference is used.</p>
</div>
<div class="section" title="Compound Statement">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="src_psm_compound"></a>Compound Statement</h3>
</div>
</div>
</div>
<p>A compound statement is enclosed in a BEGIN / END block with
      optional labels. It can contain one or more <code class="literal">&lt;SQL variable
      declaration&gt;</code>, <code class="literal">&lt;declare cursor&gt;</code> or
      <code class="literal">&lt;handler declaration&gt;</code> before at least one SQL
      statement. The BNF is given below:</p>
<p>
<code class="literal">&lt;compound statement&gt; ::= [ &lt;beginning
      label&gt; &lt;colon&gt; ] BEGIN [[NOT] ATOMIC]</code>
</p>
<p>
<code class="literal">[{&lt;SQL variable declaration&gt; &lt;semicolon&gt;}
      ...]</code>
</p>
<p>
<code class="literal">[{&lt;declare cursor&gt; &lt;semicolon&gt;}
      ...]</code>
</p>
<p>
<code class="literal">[{&lt;handler declaration&gt; &lt;semicolon&gt;}...]
      </code>
</p>
<p>
<code class="literal">{&lt;SQL procedure statement&gt; &lt;semicolon&gt;}
      ... </code>
</p>
<p>
<code class="literal">END [ &lt;ending label&gt; ]</code>
</p>
<p>An example of a simple compound statement body is given below. It
      performs the common task of inserting related data into two table. The
      IDENTITY value that is automatically inserted in the first table is
      retrieved using the IDENTITY() function and inserted into the second
      table. Other examples show more complex compound statements.</p>
<pre class="programlisting"> CREATE PROCEDURE new_customer(firstname VARCHAR(50), lastname  VARCHAR(50), address VARCHAR(100))
   MODIFIES SQL DATA
     BEGIN ATOMIC
     INSERT INTO customers VALUES (DEFAULT, firstname, lastname, CURRENT_TIMESTAMP);
     INSERT INTO addresses VALUES (DEFAULT, IDENTITY(), address);
   END

</pre>
</div>
<div class="section" title="Table Variables">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="src_psm_table_vars"></a>Table Variables</h3>
</div>
</div>
</div>
<p>A <code class="literal">&lt;table variable declaration&gt;</code> defines
      the name and columns of a local table, that can be used in the routine
      body. The table cannot have constraints. Table variable declarations are
      made before scalar variable declarations.</p>
<pre class="programlisting"> BEGIN ATOMIC
   DECLARE TABLE temp_table (col_a INT, col_b VARCHAR(20);
   DECLARE temp_id INTEGER;
   -- more statements
 END

</pre>
</div>
<div class="section" title="Variables">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="src_psm_vars"></a>Variables</h3>
</div>
</div>
</div>
<p>A <code class="literal">&lt;variable declaration&gt;</code> defines the name
      and data type of the variable and, optionally, its default value. In the
      next example, a variable is used to hold the IDENTITY value. In
      addition, the formal parameters of the procedure are identified as input
      parameters with the use of the optional IN keyword. This procedure does
      exactly the same job as the procedure in the previous example.</p>
<pre class="programlisting"> CREATE PROCEDURE new_customer(IN firstname VARCHAR(50), IN lastname VARCHAR(50), IN address VARCHAR(100))
     MODIFIES SQL DATA
   BEGIN ATOMIC
     DECLARE temp_id INTEGER;
     INSERT INTO CUSTOMERS VALUES (DEFAULT, firstname, lastname, CURRENT_TIMESTAMP);
     SET temp_id = IDENTITY();
     INSERT INTO ADDRESSES VALUES (DEFAULT, temp_id, address);
   END

</pre>
<p>The BNF for variable declaration is given below:</p>
<a name="N12FF8" class="indexterm"></a>
<p>
<span class="bold"><strong>DECLARE variable</strong></span>
</p>
<p>
<span class="emphasis"><em>SQL variable declaration</em></span>
</p>
<p>
<code class="literal">&lt;SQL variable declaration&gt; ::= DECLARE
      &lt;variable name list&gt; &lt;data type&gt; [DEFAULT &lt;default
      value&gt;]</code>
</p>
<p>
<code class="literal">&lt;variable name list&gt; ::= &lt;variable name&gt; [
      { &lt;comma&gt; &lt;variable name&gt; }... ]</code>
</p>
<p>Examples of variable declaration are given below. Note that in a
      DECLARE statement with multiple comma-separated variable names, the type
      and the default value applies to all the variables in the list:</p>
<pre class="programlisting"> BEGIN ATOMIC
   DECLARE temp_zero DATE;
   DECLARE temp_one, temp_two INTEGER DEFAULT 2;
   DECLARE temp_three VARCHAR(20) DEFAULT 'no name';
   -- more statements ...
   SET temp_zero = DATE '2010-03-18';
   SET temp_two = 5;
   -- more statements ...
 END</pre>
</div>
<div class="section" title="Cursors">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="src_psm_cursors"></a>Cursors</h3>
</div>
</div>
</div>
<p>A <code class="literal">&lt;declare cursor&gt;</code> statement is used to
      declare a SELECT statement. The current usage of this statement in early
      versions of HyperSQL 2.0 is exclusively to return a result set from a
      procedure. The result set is returned to the JDBC CallableStatement
      object that calls the procedure. The getResultSet() method of
      CallableStatement is then used to retrieve the JDBC ResultSet.</p>
<p>In the <code class="literal">&lt;routine definition&gt;</code>, the
      <code class="literal">DYNAMIC RESULT SETS</code> clause must be used to specify a
      value above zero. The <code class="literal">DECLARE CURSOR</code> statement is
      used after any variable declaration in compound statement block. The
      SELECT statement should be followed with FOR READ ONLY to avoid possible
      error messages. The <code class="literal">&lt;open statement&gt;</code> is then
      executed for the cursor at the point where the result set should be
      populated.</p>
<p>After the procedure is executed with a JDBC CallableStatement
      execute() method, all the result sets that were opened are returned to
      the JDBC CallableStatement.</p>
<p>Calling getResultSet() will return the first ResultSet. When there
      are multiple result sets, the getMoreResults() method of the Callable
      statement is called to move to the next ResultSet, before getResultSet()
      is called to return the next ResultSet. See the <a class="link" href="#dataaccess-chapt" title="Chapter&nbsp;7.&nbsp;Data Access and Change">Data Access and Change</a> chapter
      on the syntax for declaring the cursor.</p>
<pre class="programlisting"> BEGIN ATOMIC
   DECLARE temp_zero DATE;
   DECLARE result CURSOR WITH RETURN FOR SELECT * FROM INFORMATION_SCHEMA.TABLES FOR READ ONLY;
   -- more statements ...
   OPEN result;
 END
</pre>
</div>
<div class="section" title="Handlers">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="src_psm_handlers"></a>Handlers</h3>
</div>
</div>
</div>
<p>A <code class="literal">&lt;handler declaration&gt;</code> defines the
      course of action when an exception or warning is raised during the
      execution of the compound statement. A compound statement may have one
      or more handler declarations. These handlers become active when code
      execution enters the compound statement block and remain active in any
      sub-block and statement within the block. The handlers become inactive
      when code execution leaves the block.</p>
<p>In the previous example of the <code class="literal">new_customer</code>
      procedure, if an exception is thrown during the execution of either SQL
      statement, the execution of the compound statement is terminated and the
      exception is propagated and thrown by the CALL statement for the
      procedure. All changes made by the procedure are rolled back.</p>
<p>A handler declaration can resolve the thrown exception within the
      compound statement without propagating it, and allow the execution of
      the compound statement to continue.</p>
<p>In the example below, the <code class="literal">UNDO</code> handler
      declaration catches any exception that is thrown during the execution of
      the compound statement inside the <code class="literal">BEGIN ... END</code>
      block. As it is an <code class="literal">UNDO</code> handler, all the changes to
      data performed within the compound statement ( <code class="literal">BEGIN ...
      END</code> block) are rolled back. The procedure then returns without
      throwing an exception.</p>
<pre class="programlisting"> CREATE PROCEDURE new_customer(IN firstname VARCHAR(50), IN lastname VARCHAR(50), IN address VARCHAR(100))
     MODIFIES SQL DATA
   label_one: BEGIN ATOMIC
     DECLARE temp_id INTEGER;
     DECLARE UNDO HANDLER FOR SQLEXCEPTION;
     INSERT INTO CUSTOMERS VALUES (DEFAULT, firstname, lastname, CURRENT_TIMESTAMP);
     SET temp_id = IDENTITY();
     INSERT INTO ADDRESSES VALUES (DEFAULT, temp_id, address);
   END

</pre>
<p>Other types of hander are <code class="literal">CONTINUE</code> and
      <code class="literal">EXIT</code> handlers. A <code class="literal">CONTINUE</code> handler
      ignores any exception and proceeds to the next statement in the block.
      An <code class="literal">EXIT</code> handler terminates execution without undoing
      the data changes performed by the previous (successful)
      statements.</p>
<p>The conditions can be general conditions, or specific
      conditions.</p>
<p>Among general conditions that can be specified,
      <code class="literal">SQLEXCEPTION</code> covers all exceptions,
      <code class="literal">SQLWARNING</code> covers all warnings, while <code class="literal">NOT
      FOUND</code> covers the not-found condition, which is raised when a
      DELETE, UPDATE, INSERT or MERGE statement completes without actually
      affecting any row.</p>
<p>Alternatively, one or more specific conditions can be specified
      (separated with commas) which apply to specific exceptions or warnings
      or classes or exceptions or warnings. A specific condition is specified
      with <code class="literal">SQLSTATE &lt;value&gt;</code>, for example
      <code class="literal">SQLSTATE 'W_01003'</code> specifies the warning raised after
      a SQL statement is executed which contains an aggregate function which
      encounters a null value during execution. An example is given below
      which activates the handler when either of the two warnings is
      raised:</p>
<pre class="programlisting"> DECLARE UNDO HANDLER FOR SQLSTATE 'W_01003', 'W_01004';</pre>
<p>The BNF for <code class="literal">&lt;handler declaration&gt;</code> is
      given below:</p>
<a name="N13079" class="indexterm"></a>
<p>
<span class="bold"><strong>DECLARE HANDLER</strong></span>
</p>
<p>
<span class="emphasis"><em>declare handler statement</em></span>
</p>
<p>
<code class="literal">&lt;handler declaration&gt; ::= DECLARE {UNDO |
      CONTINUE | EXIT} HANDLER FOR {SQLEXCEPTION | SQLWARNING | NOT FOUND} | {
      SQLSTATE &lt;state value&gt; [, ...]} [&lt;SQL procedure
      statement&gt;];</code>
</p>
<p>A handler declaration may specify an <code class="literal">&lt;SQL procedure
      statement&gt;</code> to be performed when the handler is activated.
      In the example below the handler performs the <code class="literal">UNDO</code> as
      in the previous example then inserts the (invalid) data into a separate
      table.</p>
<pre class="programlisting"> CREATE PROCEDURE new_customer(IN firstname VARCHAR(50), IN lastname VARCHAR(50), IN address VARCHAR(100))
     MODIFIES SQL DATA
   label_one: BEGIN ATOMIC
     DECLARE temp_id INTEGER;
     DECLARE UNDO HANDLER FOR SQLEXCEPTION
     INSERT INTO invalid_customers VALUES(firstanme, lastname, address);
     -- last statement is part of the handler
     INSERT INTO CUSTOMERS VALUES (DEFAULT, firstname, lastname, CURRENT_TIMESTAMP);
     SET temp_id = IDENTITY();
     INSERT INTO ADDRESSES VALUES (DEFAULT, temp_id, address);
   END
</pre>
<p>The <code class="literal">&lt;SQL procedure statement&gt;</code> in the
      handler declaration is required by the SQL Standard but is optional in
      HyperSQL. If the execution of the <code class="literal">&lt;SQL procedure
      statement&gt;</code> specified in the handler declaration throws an
      exception itself, then it is handled by the handlers that are currently
      active at an enclosing (outer) <code class="literal">BEGIN ... END</code> block.
      The <code class="literal">&lt;SQL procedure statement&gt;</code> can itself be a
      compound statement with its own handlers.</p>
<p>When a handler handles an exception condition such as the general
      <code class="literal">SQLEXCEPTION</code> or some specific
      <code class="literal">SQLSTATE</code>, any changes made by the statement that
      caused the exception will be rolled back. For example, execution of a
      single update statement that modifies several rows will not change any
      row if an exception occurs during the update of one of the rows. The
      handler action affects the changes made by statements that were executed
      successfully before the exception occured.</p>
<p>Actions performed by different types of handler are listed
      below:</p>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>An <code class="literal">UNDO</code> handler rolls back all the data
          changes within the <code class="literal">BEGIN ... END</code> block which
          contains the handler declaration. The execution of the
          <code class="literal">BEGIN ... END</code> block is considered complete. If an
          <code class="literal">&lt;SQL procedure statement&gt;</code> is specified, it
          is executed after the roll back.</p>
</li>
<li class="listitem">
<p>A <code class="literal">CONTINUE</code> handler does not roll back the
          data changes. It continues execution as if the last statement was
          successful. If an <code class="literal">&lt;SQL procedure statement&gt;</code>
          is specified, it is executed before continuing execution.</p>
</li>
<li class="listitem">
<p>An <code class="literal">EXIT</code> handler does not roll back the data
          changes. It aborts the execution of the <code class="literal">BEGIN ...
          END</code> block which contains the handler declaration. The
          execution of the <code class="literal">BEGIN ... END</code> block is
          considered complete, but unlike the <code class="literal">UNDO</code> handler
          the actions are not rolled back. If an <code class="literal">&lt;SQL procedure
          statement&gt;</code> is specified, it is executed before
          aborting.</p>
</li>
</ul>
</div>
</div>
<div class="section" title="Assignment Statement">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="src_psm_assignment"></a>Assignment Statement</h3>
</div>
</div>
</div>
<p>The SET statement is used for assignment. It can be used flexibly
      with rows or single values. The BNF is given below:</p>
<p>
<code class="literal">&lt;assignment statement&gt; ::= &lt;singleton
      variable assignment&gt; | &lt;multiple variable
      assignment&gt;</code>
</p>
<p>
<code class="literal">&lt;singleton variable assignment&gt; ::= SET
      &lt;assignment target&gt; &lt;equals operator&gt; &lt;assignment
      source&gt;</code>
</p>
<p>
<code class="literal">&lt;multiple variable assignment&gt; ::= SET
      (&lt;variable or parameter&gt;, ...) = &lt;row value
      expression&gt;</code>
</p>
<p>In the example below, the result of the SELECT is assigned to two
      OUT or INOUT arguments. The SELECT must return one row. If it returns
      more than one, an exception is raised. If it returns no row, no change
      is made to ARG1 and ARG2.</p>
<pre class="programlisting"> SET (arg1, arg2) = (SELECT col1, col2 FROM atable WHERE id = 10);</pre>
<p>In the example below, the result of a function call is assigned to
      VAR1.</p>
<pre class="programlisting"> SET var1 = SQRT(var2);</pre>
</div>
<div class="section" title="Select Statement : Single Row">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="src_psm_select_single"></a>Select Statement : Single Row</h3>
</div>
</div>
</div>
<p>A special form of SELECT can also be used for assigning values
      from a query to one or more arguments or variables. This works similar
      to a SET statement that has a SELECT statement as the source.</p>
<a name="N130F2" class="indexterm"></a>
<p>
<span class="bold"><strong>SELECT : SINGLE ROW</strong></span>
</p>
<p>
<span class="emphasis"><em>select statement: single row</em></span>
</p>
<p>
<code class="literal">&lt;select statement: single row&gt; ::= SELECT [
      &lt;set quantifier&gt; ] &lt;select list&gt; INTO &lt;select target
      list&gt; &lt;table expression&gt;</code>
</p>
<p>
<code class="literal">&lt;select target list&gt; ::= &lt;target
      specification&gt; [ { &lt;comma&gt; &lt;target specification&gt; }...
      ]</code>
</p>
<p>Retrieve values from a specified row of a table and assign the
      fields to the specified targets. The example below has an identical
      effect to the example of SET statement given above.</p>
<pre class="programlisting">SELECT col1, col2 INTO arg1, arg2 FROM atable WHERE id = 10;</pre>
</div>
<div class="section" title="Formal Parameters">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="src_formal_parameters"></a>Formal Parameters</h3>
</div>
</div>
</div>
<p>Each parameter of a procedure can be defined as IN, OUT or INOUT.
      An IN parameter is an input to the procedure and is passed by value. The
      value cannot be modified inside the procedure body. An OUT parameter is
      a reference for output. An INOUT parameter is a reference for both input
      and output. An OUT or INOUT parameter argument is passed by reference,
      therefore only a dynamic parameter argument or a variable within an
      enclosing procedure can be passed for it. The assignment statement is
      used to assign a value to an OUT or INOUT parameter.</p>
<p>In the example below, the procedure is declared with an OUT
      parameter. It assigns the auto-generated IDENTITY value from the INSERT
      statement to the OUT argument.</p>
<pre class="programlisting"> CREATE PROCEDURE new_customer(OUT newid INT, IN firstname VARCHAR(50), IN lastname VARCHAR(50), IN address VARCHAR(100))
   MODIFIES SQL DATA
   BEGIN ATOMIC
     DECLARE temp_id INTEGER;
     INSERT INTO CUSTOMERS VALUES (DEFAULT, firstname, lastname, CURRENT_TIMESTAMP);
     SET temp_id = IDENTITY();
     INSERT INTO ADDRESSES VALUES (DEFAULT, temp_id, address);
     SET newid = temp_id;
   END

</pre>
<p>In the SQL session, or in the body of another stored procedure, a
      variable must be assigned to the OUT parameter. After the procedure
      call, this variable will hold the new identity value that was generated
      inside the procedure. If the procedure is called directly, using the
      JDBC CallableStatement interface, then the value of the first, OUT
      argument can be retrieved with a call to
      <code class="literal">getInt(1)</code>after calling the execute() method.</p>
<p>In the example below, a session variable,
      <code class="literal">the_new_id</code> is declared. After the call to
      <code class="literal">new_customer</code>, the value for the identity is stored in
      <code class="literal">the_new_id</code> variable. This is returned via the next
      CALL statement. Alternatively, <code class="literal">the_new_id</code> can be used
      as an argument to another CALL statement.</p>
<pre class="programlisting"> DECLARE the_new_id INT DEFAULT NULL;
 CALL new_customer(the_new_id, 'John', 'Smith', '10 Parliament Square'); 
 CALL the_new_id;

</pre>
</div>
<div class="section" title="Iterated Statements">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="src_psm_iterated_statements"></a>Iterated Statements</h3>
</div>
</div>
</div>
<p>Various iterated statements can be used in routines. In these
      statements, the <code class="literal">&lt;SQL statement list&gt;</code> consists
      of one or more SQL statements. The <code class="literal">&lt;search
      condition&gt;</code> can be any valid SQL expression of BOOLEAN
      type.</p>
<a name="N13133" class="indexterm"></a>
<p>
<span class="bold"><strong>LOOP</strong></span>
</p>
<p>
<span class="emphasis"><em>loop statement</em></span>
</p>
<p>
<code class="literal">&lt;loop statement&gt; ::= [ &lt;beginning label&gt;
      &lt;colon&gt; ] LOOP &lt;SQL statement list&gt; END LOOP [ &lt;ending
      label&gt; ]</code>
</p>
<a name="N13142" class="indexterm"></a>
<p>
<span class="bold"><strong>WHILE</strong></span>
</p>
<p>
<span class="emphasis"><em>while statement</em></span>
</p>
<p>
<code class="literal">&lt;while statement&gt; ::= [ &lt;beginning label&gt;
      &lt;colon&gt; ] WHILE &lt;search condition&gt; DO &lt;SQL statement
      list&gt; END WHILE [ &lt;ending label&gt; ]</code>
</p>
<a name="N13151" class="indexterm"></a>
<p>
<span class="bold"><strong>REPEAT</strong></span>
</p>
<p>
<span class="emphasis"><em>repeat statement</em></span>
</p>
<p>
<code class="literal">&lt;repeat statement&gt; ::= [ &lt;beginning label&gt;
      &lt;colon&gt; ]</code>
</p>
<p>
<code class="literal">REPEAT &lt;SQL statement list&gt; UNTIL &lt;search
      condition&gt; END REPEAT [ &lt;ending label&gt;</code>
</p>
<p>In the example below, a multiple rows are inserted into a table in
      a WHILE loop:</p>
<pre class="programlisting"> loop_label: WHILE my_var &gt; 0 DO
   INSERT INTO CUSTOMERS VALUES (DEFAULT, my_var);
   SET my_var = my_var - 1;
   IF my_var = 10 THEN SET my_var = 8; END IF;
   IF my_var = 22 THEN LEAVE loop_label; END IF;
 END WHILE loop_label;

</pre>
</div>
<div class="section" title="Iterated FOR Statement">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="src_psm_for_statement"></a>Iterated FOR Statement</h3>
</div>
</div>
</div>
<p>The <code class="literal">&lt;for statement&gt;</code> is similar to other
      iterated statement, but it is always used with a cursor declaration to
      iterate over the rows of the result set of the cursor and perform
      operations using the values of each row.</p>
<a name="N13170" class="indexterm"></a>
<p>
<span class="bold"><strong>FOR</strong></span>
</p>
<p>
<span class="emphasis"><em>for statement</em></span>
</p>
<p>
<code class="literal">&lt;for statement&gt; ::= [ &lt;beginning label&gt;
      &lt;colon&gt; ] FOR &lt;query expression&gt; DO &lt;SQL statement
      list&gt; END FOR [ &lt;ending label&gt; ]</code>
</p>
<p>The &lt;query expression&gt; is a SELECT statement. When the FOR
      statement is executed, the query expression is executed first and the
      result set is formed. Then for each row of the result set, the
      <code class="literal">&lt;SQL statement list&gt;</code> is executed. What is
      special about the FOR statement is that all the columns of the current
      row can be accessed by name in the statements in the <code class="literal">&lt;SQL
      statement list&gt;</code>. The columns are read only and cannot be
      updated. For example, if the column names for the select statement are
      ID, FIRSTNAME, LASTNAME, then these can be accessed as a variable name.
      The column names must be unique and not equivalent to any parameter or
      variable name in scope.</p>
<p>The FOR statement is useful for computing values over multiple
      rows of the result set, or for calling a procedure for some row of the
      result set.</p>
<p>In the example below, the procedure uses a FOR statement to
      iterate over the rows for a customer with lastname equal to name_p. No
      action is performed for the first row, but for all the subsequent rows,
      the row is deleted from the table.</p>
<p>Note the following: The result set for the SELECT statement is
      built only once, before processing the statements inside the FOR block
      begins. For all the rows of the SELECT statement apart from the first
      row, the row is deleted from the customer table. The WHERE condition
      uses the automatic variable id, which holds the customer.id value for
      the current row of the result set, to delete the row. The procedure
      updates the val_p argument and when it returns, the val_p represents the
      total count of rows with the given lastname before the duplicates were
      deleted.</p>
<pre class="programlisting"> CREATE PROCEDURE test_proc(INOUT val_p INT, IN lastname_p VARCHAR(20)) 
 MODIFIES SQL DATA
 BEGIN ATOMIC
   SET val_p = 0;
   for_label: FOR SELECT * FROM customer WHERE lastname = lastname_p DO
     IF  val_p &gt; 0 THEN
       DELETE FROM customer WHERE customer.id = id;
     END IF;
     SET val_p = val_p + 1;
   END FOR for_label;
 END
</pre>
</div>
<div class="section" title="Conditional Statements">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="src_psm_conditional"></a>Conditional Statements</h3>
</div>
</div>
</div>
<p>There are two types of CASE ... WHEN statement and the IF ... THEN
      statement.</p>
<a name="N13195" class="indexterm"></a>
<p>
<span class="bold"><strong>CASE WHEN</strong></span>
</p>
<p>
<span class="emphasis"><em>case when statement</em></span>
</p>
<p>The simple case statement uses a <code class="literal">&lt;case
      operand&gt;</code> as the predicand of one or more predicates. For
      the right part of each predicate, it specifies one or more SQL
      statements to execute if the predicate evaluates TRUE. If the ELSE
      clause is not specified, at least one of the search conditions must be
      true, otherwise an exception is raised.</p>
<p>
<code class="literal">&lt;simple case statement&gt; ::= CASE &lt;case
      operand&gt; &lt;simple case statement when clause&gt;... [ &lt;case
      statement else clause&gt; ] END CASE</code>
</p>
<p>
<code class="literal">&lt;simple case statement when clause&gt; ::= WHEN
      &lt;when operand list&gt; THEN &lt;SQL statement
      list&gt;</code>
</p>
<p>
<code class="literal">&lt;case statement else clause&gt; ::= ELSE &lt;SQL
      statement list&gt;</code>
</p>
<p>A skeletal example is given below. The variable var_one is first
      tested for equality with 22 or 23 and if the test evaluates to TRUE,
      then the INSERT statement is performed and the statement ends. If the
      test does not evaluate to TRUE, the next condition test, which is an IN
      predicate, is performed with var_one and so on. The statement after the
      ELSE clause is performed if none the previous tests returns TRUE.</p>
<pre class="programlisting">CASE var_one
  WHEN 22, 23 THEN INSERT INTO t_one ...;
  WHEN IN (2, 4, 5) THEN DELETE FROM t_one WHERE ...;
  ELSE UPDATE t_one ...;
  END CASE

</pre>
<p>The searched case statement uses one or more search conditions,
      and for each search condition, it specifies one or more SQL statements
      to execute if the search condition evaluates TRUE. An exception is
      raised if there is no ELSE clause and none of the search conditions
      evaluates TRUE.</p>
<p>
<code class="literal">&lt;searched case statement&gt; ::= CASE &lt;searched
      case statement when clause&gt;... [ &lt;case statement else clause&gt; ]
      END CASE</code>
</p>
<p>
<code class="literal">&lt;searched case statement when clause&gt; ::= WHEN
      &lt;search condition&gt; THEN &lt;SQL statement
      list&gt;</code>
</p>
<p>The example below is partly a rewrite of the previous example, but
      a new condition is added:</p>
<pre class="programlisting"> CASE WHEN var_one = 22 OR var_one = 23 THEN INSERT INTO t_one ...;
   WHEN var_one IN (2, 4, 5) THEN DELETE FROM t_one WHERE ...;
   WHEN var_two IS NULL THEN UPDATE t_one ...;
   ELSE UPDATE t_one ...;
   END CASE

</pre>
<a name="N131BF" class="indexterm"></a>
<p>
<span class="bold"><strong>IF</strong></span>
</p>
<p>
<span class="emphasis"><em>if statement</em></span>
</p>
<p>The if statement is very similar to the searched case statement.
      The difference is that no exception is raised if there is no ELSE clause
      and no search condition evaluates TRUE.</p>
<p>
<code class="literal">&lt;if statement&gt; ::= IF &lt;search condition&gt;
      &lt;if statement then clause&gt; [ &lt;if statement elseif clause&gt;...
      ] [ &lt;if statement else clause&gt; ] END IF</code>
</p>
<p>
<code class="literal">&lt;if statement then clause&gt; ::= THEN &lt;SQL
      statement list&gt;</code>
</p>
<p>
<code class="literal">&lt;if statement elseif clause&gt; ::= ELSEIF
      &lt;search condition&gt; THEN &lt;SQL statement
      list&gt;</code>
</p>
<p>
<code class="literal">&lt;if statement else clause&gt; ::= ELSE &lt;SQL
      statement list&gt;</code>
</p>
</div>
<div class="section" title="Return Statement">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="src_psm_return_statement"></a>Return Statement</h3>
</div>
</div>
</div>
<p>The RETURN statement is required and used only in functions. The
      body of a function is either a RETURN statement, or a compound statement
      that contains a RETURN statement.</p>
<p>The return value of a FUNCTION can be assigned to a variable, or
      used inside an SQL statement.</p>
<p>An SQL/PSM function or an SQL/JRT function can return a single
      result when the function is defined as RETURNS TABLE ( .. )</p>
<p>To return a table from a SELECT statement, you should use a return
      statement such as RETURN TABLE( SELECT ...) in an SQL/PSM function. For
      an SQL/JRT function, the Java method should return a JDBCResultSet
      instance.</p>
<p>To call a function from JDBC, use a java.sql.CallableStatement
      instance. The <code class="literal">getResultSet()</code> call can be used to
      access the ResultSet returned from a function that returns a result set.
      If the function returns a scalar value, the returned result has a single
      column and a single row which contains the scalar returned value.</p>
<a name="N131EA" class="indexterm"></a>
<p>
<span class="bold"><strong>RETURN</strong></span>
</p>
<p>
<span class="emphasis"><em>return statement</em></span>
</p>
<p>
<code class="literal">&lt;return statement&gt; ::= RETURN &lt;return
      value&gt;</code>
</p>
<p>
<code class="literal">&lt;return value&gt; ::= &lt;value expression&gt; |
      NULL</code>
</p>
<p>Return a value from an SQL function. If the function is defined
      as RETURNS TABLE, then the value is a TABLE expression such as RETURN
      TABLE(SELECT ...) otherwise, the value expression can be any scalar
      expression. In the examples below, the same function is written with or
      without a BEGIN END block. In both versions, the RETURN value is a
      scalar expression.</p>
<pre class="programlisting"> CREATE FUNCTION an_hour_before_max (e_type INT)
   RETURNS TIMESTAMP
   RETURN (SELECT MAX(event_time) FROM atable WHERE event_type = e_type) - 1 HOUR

 CREATE FUNCTION an_hour_before_max (e_type INT)
   RETURNS TIMESTAMP
   BEGIN ATOMIC
     DECLARE max_event TIMESTAMP;
     SET max_event = SELECT MAX(event_time) FROM atable WHERE event_type = e_type;
     RETURN max_event - 1 HOUR;
   END

</pre>
</div>
<div class="section" title="Control Statements">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="src_psm_control_statements"></a>Control Statements</h3>
</div>
</div>
</div>
<p>In addition to the RETURN statement, the following statements can
      be used in specific contexts.</p>
<p>ITERATE STATEMENT</p>
<p>The ITERATE statement can be used to cause the next iteration of a
      labelled iterated statement (a WHILE, REPEAT or LOOP statement). It is
      similar to the "continue" statement in C and Java.</p>
<p>
<code class="literal">&lt;iterate statement&gt; ::= ITERATE &lt;statement
      label&gt;</code>
</p>
<p>LEAVE STATEMENT</p>
<p>The LEAVE statement can be used to leave a labelled block. When
      used in an iterated statement, it is similar to the "break" statement is
      C and Java. But it can be used in compound statements as well.</p>
<p>
<code class="literal">&lt;leave statement&gt; ::= LEAVE &lt;statement
      label&gt;</code>
</p>
</div>
<div class="section" title="Raising Exceptions">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="src_psm_exceptions"></a>Raising Exceptions</h3>
</div>
</div>
</div>
<p>Signal and Resignal Statements allow the routine to throw an
      exception. If used with the IF or CASE conditions, the exception is
      thrown conditionally.</p>
<a name="N1321A" class="indexterm"></a>
<p>
<span class="bold"><strong>SIGNAL</strong></span>
</p>
<p>
<span class="emphasis"><em>signal statement</em></span>
</p>
<p>The SIGNAL statement is used to throw an exception (or force an
      exception). When invoked, any exception handler for the given exception
      is in turn invoked. If there is no handler, the exception is propagated
      to the enclosing context. In its simplest form, when there is no
      exception handler for the given exception, routine execution is halted,
      any change of data is rolled back and the routine throws the exception.
      By default, the message for the exception is taken from the predefined
      exception message for the specified SQLSTATE. A custom message can be
      specified with the optional SET clause.</p>
<p>
<code class="literal">&lt;signal statement&gt; ::= SIGNAL SQLSTATE &lt;state
      value&gt; [ SET MESSAGE_TEXT = &lt;character string literal&gt; ]
      </code>
</p>
<a name="N1322B" class="indexterm"></a>
<p>
<span class="bold"><strong>RESIGNAL</strong></span>
</p>
<p>
<span class="emphasis"><em>resignal statement</em></span>
</p>
<p>The RESIGNAL statement is used to throw an exception from an
      exception handler's <code class="literal">&lt;SQL procedure statement&gt;</code>,
      in effect propagating the exception to the enclosing context without
      further action by the currently active handlers. By default, the message
      for the exception is taken from the predefined exception message for the
      specified SQLSTATE. A custom message can be specified with the optional
      SET clause.</p>
<p>
<code class="literal">&lt;resignal statement&gt; ::= RESIGNAL SQLSTATE
      &lt;state value&gt; [ SET MESSAGE_TEXT = &lt;character string
      literal&gt; ]</code>
</p>
</div>
<div class="section" title="Routine Polymorphism">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="src_routine_polymorphism"></a>Routine Polymorphism</h3>
</div>
</div>
</div>
<p>More than one version of a routine can be created.</p>
<p>For procedures, the different versions must have different
      parameter counts. When the procedure is called, the parameter count
      determines which version is called.</p>
<p>For functions, the different versions can have the same or
      different parameter counts. When the parameter count of two versions of
      a function is the same, the type of parameters must be different. When
      the function is called, the best matching version of the function is
      used, according to both the parameter count and parameter types. The
      return type of different versions of a function can be the same or
      different.</p>
<p>Two versions of an overloaded function are given below. One
      version accepts TIMESTAMP while the other accepts TIME arguments.</p>
<pre class="programlisting"> CREATE FUNCTION an_hour_before_or_now(t TIMESTAMP)
   RETURNS TIMESTAMP
   IF t &gt; CURRENT_TIMESTAMP THEN
     RETURN CURRENT_TIMESTAMP;
   ELSE
     RETURN t - 1 HOUR;
   END IF

 CREATE FUNCTION an_hour_before_or_now(t TIME)
   RETURNS TIME
   CASE t
     WHEN &gt; CURRENT_TIME THEN
       RETURN CURRENT_TIME;
     WHEN &gt;= TIME'01:00:00' THEN
       RETURN t - 1 HOUR;
     ELSE
       RETURN CURRENT_TIME;
   END CASE

</pre>
<p>It is perfectly possible to have different versions of the routine
      as SQL/JRT or SQL/PSM routines.</p>
</div>
<div class="section" title="Returning Data From Procedures">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="src_returning_data"></a>Returning Data From Procedures</h3>
</div>
</div>
</div>
<p>The OUT or INOUT parameters of a PROCEDURE are used to assign
      simple values to dynamic parameters or to variables in the calling
      context.</p>
<p>According to the Standard, an SQL/PSM or SQL/JRT procedure may
      also return result sets to the calling context. These result sets are
      dynamic in the sense that a procedure may return a different number of
      result sets or none at all in different invocations. The SQL Standard
      uses a mechanism called CURSORS for accessing and modifying rows of a
      result set one by one. This mechanism is necessary when the database is
      accessed from an external application program. The JDBC ResultSet
      interface allows this method of access from Java programs and is
      supported by HyperSQL.</p>
<p>HyperSQL support this method of returning single or multiple
      result sets from SQL/PSM procedures only via the JDBC CallableStatement
      interface. Cursors are declared and opened within the body of the
      procedure. No further operation is performed on the cursors within the
      procedure. When the execution of the procedure is complete, the cursors
      become available as Java ResultSet objects via the CallableStatement
      instance that called the SQL/PSM procedure.</p>
<p>The JDBC CallableStatement class is used with the SQL statement
      <code class="literal">CALL &lt;routine name&gt; ( &lt;argument 1&gt;, ... )</code>
      to call procedures (also to call functions). After the call to
      execute(), the <code class="literal">getXXX()</code> methods can be used to
      retrieve INOUT or OUT arguments after the call. The getMoreResults()
      method and the <code class="literal">getResultSet()</code> method can be used to
      access the ResultSet(s) returned by a procedure that returns one or more
      results. If the procedure returns more than one result set, the
      <code class="literal">getMoreResults()</code> call moves to the next
      result.</p>
<p>In the example below, the procedure inserts a row into the
      customer table. It then performs the SELECT statement to return the
      latest inserted row as a result set. Therefore the definition includes
      the <code class="code">DYNAMIC RESULT SETS 1</code> clause. You must specify
      correctly the maximum number of result sets that the procedure may
      return.</p>
<pre class="programlisting"> CREATE PROCEDURE new_customer(firstname VARCHAR(50), lastname VARCHAR(50))
   MODIFIES SQL DATA DYNAMIC RESULT SETS 1
   BEGIN ATOMIC
     DECLARE result CURSOR FOR SELECT * FROM CUSTOMERS WHERE ID = IDENTITY();
     INSERT INTO CUSTOMERS VALUES (DEFAULT, firstname, lastname, CURRENT_TIMESTAMP);
     OPEN result;    
   END

</pre>
<p>The above procedure is called in Java using a
      CallableStatement</p>
<pre class="programlisting"> Connection conn = ...;
 CallableStatement call = conn.prepareCall("call new_customer(?, ?)");
 call.setString(1, "Paul");
 call.setString(2, "Smith");
 call.execute();
 if (call.getMoreResults())
     ResultSet result = call.getResultSet();

</pre>
<p>In the example below a procedure has one IN argument and two OUT
      arguments. The JDBC CallableStatement is used to retrieve the values
      returned in the OUT arguments.</p>
<pre class="programlisting"> CREATE PROCEDURE get_customer(IN id INT, OUT firstname VARCHAR(50), OUT lastname VARCHAR(50)) 
   READS SQL DATA
   BEGIN ATOMIC
     -- this statement uses the id to get firstname and lastname
     SELECT first_name, last_name INTO firstname, lastname FROM customers WHERE cust_id = id;
   END

 Connection conn = ...;
 CallableStatement call = conn.prepareCall("call get_customer(?, ?, ?)");
 call.setInt(1, 121); // only the IN (or INOUT) arguments should be set before the call
 call.execute();
 String firstname = call.getString(2); // the OUT (or INOUT) arguments are retrieved after the call
 String lastname = call.getString(3);

</pre>
<p>SQL/JRT procedures are discussed in the Java Language Procedures
      section below. Those routines are called exactly the same way as SQL/PSM
      procedures, using the JDBC CallableStatement interface.</p>
<p>It is also possible to use a JDBC Statement or PreparedStatement
      object to call a procedure if the procedure arguments are constant. If
      the procedure returns one or more result sets, the
      Statement#getMoreResults() method should be called before retrieving the
      ResultSet.</p>
<p>Java functions are called from JDBC similar to procedures. With
      functions, the getMoreResuls() method should not be called at
      all.</p>
</div>
<div class="section" title="Recursive Routines">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="src_psm_recursive_routines"></a>Recursive Routines</h3>
</div>
</div>
</div>
<p>Routines can be recursive. Recursive functions are often functions
      that return arrays or tables. To create a recursive routine, the routine
      definition must be created first with a dummy body. Then the ALTER
      ROUTINE statement is used to define the routine body.</p>
<p>In the example below, the table contains a tree of rows each with
      a parent. The routine returns an array containing the id list of all the
      direct and indirect children of the given parent. The routine appends
      the array variable id_list with the id of each direct child and for each
      child appends the array with the id array of its children by calling the
      routine recursively.</p>
<p>The routine can be used in a SELECT statement as the example
      shows.</p>
<pre class="programlisting"> CREATE TABLE ptree (pid INT, id INT);
 INSERT INTO ptree VALUES (NULL, 1) ,(1,2), (1,3),(2,4),(4,5),(3,6),(3,7);

 -- the function is created and always throws an exception when used
 CREATE FUNCTION child_arr(p_pid INT) RETURNS INT ARRAY
   SPECIFIC child_arr_one
   READS SQL DATA
   SIGNAL SQLSTATE '45000'

 -- the actual body of the function is defined, replacing the statement that throws the exception
 ALTER SPECIFIC ROUTINE child_arr_one
   BEGIN ATOMIC
     DECLARE id_list INT ARRAY DEFAULT ARRAY[];
     for_loop:
     FOR SELECT id FROM ptree WHERE pid = p_pid DO
       SET id_list[CARDINALITY(id_list) + 1] = id;
       SET id_list = id_list || child_arr(id);
     END FOR for_loop;
     RETURN id_list;
   END

 -- the function can now be used in SQL statements
 SELECT * FROM TABLE(child_arr(2))
</pre>
<p>In the next example, a table with two columns is returned instead
      of an array. In this example, a local table variable is declared and
      filled with the children and the children's children.</p>
<pre class="programlisting"> CREATE FUNCTION child_table(p_pid INT) RETURNS TABLE(r_pid INT, r_id INT)
   SPECIFIC child_table_one
   READS SQL DATA
   SIGNAL SQLSTATE '45000'

 ALTER SPECIFIC ROUTINE child_table_one
   BEGIN ATOMIC
     DECLARE TABLE child_tree (pid INT, id INT);
     for_loop:
     FOR SELECT pid, id FROM ptree WHERE pid = p_pid DO
       INSERT INTO child_tree VALUES pid, id;
       INSERT INTO child_tree SELECT r_pid, r_id FROM TABLE(child_table(id));
     END FOR for_loop;
     RETURN TABLE(SELECT * FROM child_tree);
   END

 SELECT * FROM TABLE(child_table(1))
</pre>
<p>Infinite recursion is not possible as the routine is terminated
      when a given depth is reached.</p>
</div>
</div>
<div class="section" title="Java Language Routines (SQL/JRT)">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="src_jrt_routines"></a>Java Language Routines (SQL/JRT)</h2>
</div>
</div>
</div>
<p>The general features of SQL-Invoked Routines are shared between PSM
    and JRT routines. These features are covered in the previous section. This
    section deals with specific aspects of JRT routines.</p>
<p>The body of a Java language routine is a static method of a Java
    class, specified with a fully qualified method name in the routine
    definition. A simple CREATE FUNCTION example is given below, which defines
    the function to call the <code class="literal">java.lang.Math.sinh(double d)</code>
    Java method. The function can be called in SQL statements just like any
    built-in function.</p>
<pre class="programlisting"> CREATE FUNCTION sinh(v DOUBLE) RETURNS DOUBLE
   LANGUAGE JAVA DETERMINISTIC NO SQL
   EXTERNAL NAME 'CLASSPATH:java.lang.Math.sinh'

 SELECT sinh(doublecolumn) FROM mytable
</pre>
<p>In the example below, the static method named
    <code class="methodname">toZeroPaddedString</code> is specified to be called when
    the function is invoked.</p>
<pre class="programlisting"> CREATE FUNCTION zero_pad(x BIGINT, digits INT, maxsize INT)
   RETURNS CHAR VARYING(100)
   LANGUAGE JAVA DETERMINISTIC NO SQL
   EXTERNAL NAME 'CLASSPATH:org.hsqldb.lib.StringUtil.toZeroPaddedString'
</pre>
<p>The signature of the Java method (used in the Java code but not in
    SQL code to create the function) is given below:</p>
<pre class="programlisting"> public static String toZeroPaddedString(long value, int precision, int maxSize)</pre>
<p>The parameter and return types of the SQL routine definition must
    match those of the Java method according to the table below:</p>
<div class="informaltable">
<table cellspacing="0" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col>
<col>
</colgroup>
<tbody>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">
<p>SMALLINT &nbsp; </p>
</td><td style="border-bottom: 0.5pt solid ; ">
<p>short or Short</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">
<p>INT</p>
</td><td style="border-bottom: 0.5pt solid ; ">
<p>int or Integer</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">
<p>BIGINT</p>
</td><td style="border-bottom: 0.5pt solid ; ">
<p>long or Long</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">
<p>NUMERIC &nbsp;or DECIMAL</p>
</td><td style="border-bottom: 0.5pt solid ; ">
<p>BigDecimal</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">
<p>FLOAT &nbsp;or DOUBLE</p>
</td><td style="border-bottom: 0.5pt solid ; ">
<p>double or Double</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">
<p>CHAR or VARCHAR</p>
</td><td style="border-bottom: 0.5pt solid ; ">
<p>String</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">
<p>DATE</p>
</td><td style="border-bottom: 0.5pt solid ; ">
<p>java.sql.Date</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">
<p>TIME</p>
</td><td style="border-bottom: 0.5pt solid ; ">
<p>java.sql.Time</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">
<p>TIMESTAMP</p>
</td><td style="border-bottom: 0.5pt solid ; ">
<p>java.sql.Timestamp</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">
<p>BINARY</p>
</td><td style="border-bottom: 0.5pt solid ; ">
<p>Byte[]</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">
<p>BOOLEAN</p>
</td><td style="border-bottom: 0.5pt solid ; ">
<p>boolean or Boolean</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">ARRAY of any type</td><td style="border-bottom: 0.5pt solid ; ">java.sql.Array</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; ">
<p>TABLE</p>
</td><td style="">
<p>java.sql.ResultSet</p>
</td>
</tr>
</tbody>
</table>
</div>
<p>If the specified Java method is not found or its parameters and
    return types do not match the definition, an exception is raised. If more
    than one version of the Java method exist, then the one with matching
    parameter and return types is found and registered. If two &ldquo;equivalent&rdquo;
    methods exist, the first one is registered. (This situation arises only
    when a parameter is a primitive in one version and an Object in another
    version, e.g. <code class="classname">long</code> and
    <code class="classname">java.lang.Long</code>.).</p>
<p>When the Java method of an SQL/JRT routine returns a value, it
    should be within the size and precision limits defined in the return type
    of the SQL-invoked routine, otherwise an exception is raised. The scale
    difference are ignored and corrected. For example, in the above example,
    the <code class="literal">RETURNS CHAR VARYING(100)</code> clause limits the length
    of the strings returned from the Java method to 100. But if the number of
    digits after the decimal point (scale) of a returned BigDecimal value is
    larger than the scale specified in the RETURNS clause, the decimal
    fraction is silently truncated and no exception of warning is
    raised.</p>
<p>When the function is specified as RETURNS TABLE(...) the static Java
    method should return a JDBCResultSet instance. For an example of how to
    construct a JDBCResultSet for this purpose, see the source code for the
    org.hsqldb.jdbc.JDBCArray class.</p>
<div class="section" title="Polymorphism">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="src_jrt_polymorphis"></a>Polymorphism</h3>
</div>
</div>
</div>
<p>If two versions of the same SQL invoked routine with different
      parameter types are required, they can be defined to point to the same
      method name or different method names, or even methods in different
      classes. In the example below, the first two definitions refer to the
      same method name in the same class. In the Java class, the two static
      methods are defined with corresponding method signatures.</p>
<p>In the third example, the Java function returns a result set and
      the SQL declaration includes RETURNS TABLE.</p>
<pre class="programlisting"> CREATE FUNCTION an_hour_before_or_now(t TIME)
   RETURNS TIME
   NO SQL
   LANGUAGE JAVA PARAMETER STYLE JAVA
   EXTERNAL NAME 'CLASSPATH:org.npo.lib.nowLessAnHour'

 CREATE FUNCTION an_hour_before_or_now(t TIMESTAMP)
   RETURNS TIMESTAMP
   NO SQL
   LANGUAGE JAVA PARAMETER STYLE JAVA
   EXTERNAL NAME 'CLASSPATH:org.npo.lib.nowLessAnHour'

 CREATE FUNCTION testquery(i INTEGER) 
   RETURNS TABLE(n VARCHAR(20), i INT) 
   READS SQL DATA
   LANGUAGE JAVA
   EXTERNAL NAME 'CLASSPATH:org.hsqldb.test.TestJavaFunctions.getQueryResult'

</pre>
<p>In the Java class the definitions are as follows. Note the
      definition of the getQueryResult method begins with a
      java.sql.Connection parameter. This parameter is ignored when choosing
      the Java method. The parameter is used to pass the current JDBC
      connection to the Java method.</p>
<pre class="programlisting"> public static java.sql.Time nowLessAnHour(java.sql.Time value) {
     ...
 }

 public static java.sql.Timestamp nowLessAnHour(java.sql.Timestamp value)
     ...
 }

 public static ResultSet getQueryResult(Connection connection, int i) throws SQLException {
     Statement st = connection.createStatement();
     return st.executeQuery("SELECT * FROM T WHERE I &lt; " + i);
 }

</pre>
</div>
<div class="section" title="Java Language Procedures">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="src_jrt_procedures"></a>Java Language Procedures</h3>
</div>
</div>
</div>
<p>Java procedures are defined similarly to functions. The
      differences are:</p>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>The return type of the Java static method must be void.</p>
</li>
<li class="listitem">
<p>If a parameter is defined as OUT or INOUT, the corresponding
          Java static method parameter must be defined as an array of the JDBC
          non-primitive type.</p>
</li>
<li class="listitem">
<p>When the Java static method is invoked, the OUT and INOUT
          arguments are passed to the Java method as a single-element
          array.</p>
</li>
<li class="listitem">
<p>The static method can modify the OUT or INOUT argument by
          assigning a value to the sole element of the argument array.</p>
</li>
<li class="listitem">
<p>A procedure can return one or more result sets. These are
          instantiated as JDBC ResultSet objects by the Java static and
          returned in array arguments of the method. The signature of the Java
          method for a procedure that has N declared parameters and returns M
          result sets has the following pattern. The N parameters
          corresponding to the signature of the declared SQL procedure are
          defined first, followed by M parameters as ResultSet arrays.</p>
<p>When the SQL procedure is executed, the Java method is called
          with single element array arguments passed for OUT and INOUT SQL
          parameters, and single element arrays of ResultSet for the returned
          ResultSet objects. The Java method may call the execute() or
          executeQuery() methods of JDBC Statement or PreparedStatement
          objects that are declared within the method and assign the ResultSet
          objects to the first element of each ResultSet[] argument. For the
          returned ResultSet objects, the Java method should not call the
          methods of java.sql.ResultSet before returning.</p>
<p>
<code class="literal">void methodName(&lt;arg1&gt;, ... &lt;argN&gt;,
          ResultSet[] r1, ..., ResultSet[] rM)</code>
</p>
</li>
<li class="listitem">
<p>If the procedure contains SQL statements, only statements for
          data access and manipulation are allowed. The Java method should not
          perform commit or rollback. The SQL statements should not change the
          session settings and should not include statements that create or
          alter tables or other database objects. These rules are generally
          enforced by the engine, but additional enforcement may be added in
          future versions</p>
</li>
</ul>
</div>
<p>An example of a procedure definition, together with its Java
      signature, is given below. This procedure is the SQL/JRT version of the
      example discussed above for SQL/PSM.</p>
<pre class="programlisting"> CREATE PROCEDURE get_customer(IN id INT, OUT firstname VARCHAR(50), OUT lastname VARCHAR(50)) 
   READS SQL DATA
   LANGUAGE JAVA
   EXTERNAL NAME 'CLASSPATH:org.hsqldb.test.Test01.getCustomerProcedure'

   public static void getCustomerProcedure(int id, String[] firstn, String[] lastn)
       throws java.sql.SQLException {
       firstn[0] = somevalue;  // parameter out value is assigned
       lastn[0] = somevalue;   // parameter out value is assigned
   }

</pre>
<p>In the next example a procedure is defined to return a result set.
      The signature of the Java method is also given. The Java method assigns
      a ResultSet object to the zero element of the result parameter.</p>
<pre class="programlisting"> CREATE PROCEDURE new_customer(firstname VARCHAR(50), lastname VARCHAR(50))
   MODIFIES SQL DATA 
   LANGUAGE JAVA
   DYNAMIC RESULT SETS 1
   EXTERNAL NAME 'CLASSPATH:org.hsqldb.test.Test01.newCustomerProcedure'

   public static void newCustomerProcedure(String firstn, String lastn,
                       ResultSet[] result) throws java.sql.SQLException {
       result[0] = someresultset;  // dynamic result set is assigned
   }

</pre>
<p>Java language procedures SQL/JRT are used in an identical manner
      to SQL/PSM routines. See the section under SQL/PSM routines, Returning
      Data From Procedures, on how to use the JDBC CallableStatement interface
      to call the procedure and to get the OUT and INOUT arguments and to use
      the ResultSet objects returned by the procedure.</p>
</div>
<div class="section" title="Java Static Methods">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="src_jrt_static_methods"></a>Java Static Methods</h3>
</div>
</div>
</div>
<p>The static methods that are used for procedures and functions must
      be declared in a public class. The methods must be declared as public
      static. For functions, the method return type must be one of the JDBC
      supported types. The IN parameters of the method must be declared as one
      of the supported types. The OUT and INOUT parameters must be declared as
      Java arrays of supported types. If the SQL definition of a function
      includes RETURNS NULL ON NULL INPUT, then the IN parameters of the Java
      static function can be int or long primitives, otherwise, they must be
      Integer or Long. The declared Java arrays for OUT and INOUT parameters
      for SQL INTEGER or BIGINT must be Integer[] or Long[]
      respectively.</p>
<p>If the SQL definition of the routine includes NO SQL, then no JDBC
      method call is allowed to execute in the method body. Otherwise, a JDBC
      Connection can be used within the Java method to access the database. If
      the definition includes CONTAINS SQL, then no table data can be read. If
      the definition includes READS SQL DATA, then no table data can be
      modified. If the definition includes MODIFIES SQL DATA, then data can be
      modified. In all modes, it is not allowed to execute DDL statements that
      change the schema definition.</p>
<p>It is possible to use DECLARE LOCAL TEMPORARY TABLE in a Java
      method, as this is in the session scope.</p>
<p>There are two ways to use the JDBC Connection object.</p>
<div class="orderedlist">
<ol class="orderedlist" type="1">
<li class="listitem">
<p>Define the Java method with a Connection parameter as the
          first parameter. This parameter is "hidden" and only visible to the
          engine. The rest of the parameters, if any, are used to choose the
          method according to the required types of parameters.</p>
</li>
<li class="listitem">
<p>Use the SQL/JRT Standard
          <code class="literal">"jdbc:default:connection"</code> method. With this
          approach, the Java method does not include a Connection parameter.
          In the method body, the connection is established with a method call
          to DriverManager, as in the example below:</p>
<p>
<code class="literal">Connection con =
          DriverManager.getConnection("jdbc:default:connection");</code>
</p>
</li>
</ol>
</div>
<p>Both methods return a connection that is based on the current
      session. This connection has some extra properties, for example, the
      Close() method does not actually close it.</p>
<p>An example of an SQL PROCEDURE with its Java method definition is
      given below. The CREATE PROCEDURE statement is the same with or without
      the Connection parameter:</p>
<pre class="programlisting"> CREATE PROCEDURE proc1(IN P1 INT, IN P2 INT, OUT P3 INT)
 SPECIFIC P2 LANGUAGE JAVA DETERMINISTIC MODIFIES SQL DATA EXTERNAL NAME 'CLASSPATH:org.hsqldb.test.TestStoredProcedure.procTest2'");
</pre>
<p>In the first example, the
      <code class="literal">"jdbc:default:connection"</code> method is used. In the
      second example, a connection parameter is used</p>
<pre class="programlisting"> public static void procTest2(int p1, int p2,
                    Integer[] p3) throws java.sql.SQLException {

     Connection conn =
         DriverManager.getConnection("jdbc:default:connection");
     java.sql.Statement stmt = conn.createStatement();

     stmt.execute("INSERT INTO MYTABLE VALUES(" + p1 + ",'test1')");
     stmt.execute("INSERT INTO MYTABLE VALUES(" + p2 + ",'test2')");

     java.sql.ResultSet rs = stmt.executeQuery("select * from MYTABLE");
     java.sql.ResultSetMetaData meta = rs.getMetaData();

     int cols  = meta.getColumnCount();
     p3[0] = Integer.valueOf(cols);

     rs.close();
     stmt.close();
 }

//  alternative declaration with Connection parameter
//  public static void procTest2(Connection conn, int p1, int p2,
//                    Integer[] p3) throws java.sql.SQLException {
</pre>
<p>When the stored procedure is called by the user's program, the
      value of the OUT parameter can be read after the call.</p>
<pre class="programlisting"> // a CallableStatement is used to prepare the call
 // the OUT parameter contains the return value
 CallableStatement c = conn.prepareCall("call proc1(1,2,?)");
 c.execute();
 int value = c.getInt(1);
</pre>
</div>
<div class="section" title="Legacy Support">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="src_jrt_legacy"></a>Legacy Support</h3>
</div>
</div>
</div>
<p>The legacy HyperSQL statement, <code class="literal">CREATE ALIAS &lt;name&gt;
      FOR &lt;fully qualified Java method name&gt;</code> is no longer
      supported directly. It is supported when importing databases and
      translates to a special <code class="literal">CREATE FUNCTION &lt;name&gt;</code>
      statement that creates the function in the PUBLIC schema.</p>
<p>The direct use of a Java method as a function is still supported
      but deprecated. It is internally translated to a special <code class="literal">CREATE
      FUNCTION</code> statement where the name of the function is the
      double quoted, fully qualified name of the Java method used.</p>
</div>
<div class="section" title="Securing Access to Classes">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="src_jrt_access_control"></a>Securing Access to Classes</h3>
</div>
</div>
</div>
<p>By default, the static methods of any class that is on the
      classpath are available to be used. This can compromise security in some
      systems. The optional Java system property
      <code class="literal">hsqldb.method_class_names</code> allows preventing access to
      classes other than <code class="literal">java.lang.Math</code> or specifying a
      semicolon-separated list of allowed classes. A property value that ends
      with .* is treated as a wild card and allows access to all class or
      method names formed by substitution of the * (asterisk).</p>
<p>In the example below, the property has been included as an
      argument to the Java command.</p>
<pre class="programlisting"> java -Dhsqldb.method_class_names="org.me.MyClass;org.you.YourClass;org.you.lib.*" [the rest of the command line]
</pre>
<p>The above example allows access to the methods in the two classes:
      <code class="classname">org.me.MyClass</code> and
      <code class="classname">org.you.YourClass</code> together with all the classes
      in the <code class="classname">org.you.lib</code> package. Note that if the
      property is not defined, no access control is performed at this
      level.</p>
<p>Once the routine has been defined, the normal database access
      control still applies. The routine can be executed only by the users who
      have been granted EXECUTE privileges on it. The user who executes a Java
      routine must also have the relevant access privileges on the tables that
      are used inside the Java method.</p>
</div>
<div class="section" title="Warning">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="N133A3"></a>Warning</h3>
</div>
</div>
</div>
<p>The definition of SQL/JRT routines referencing the user's Java
      static methods is stored in the .script file of the database.</p>
<p>If the database is opened in a Java environment that does not have
      access to the referenced Java static methods on its classpath, the
      SQL/JRT routines are not created when the database is opened. When the
      database is closed, the routine definitions are lost.</p>
<p>There is a workaround to prevent opening the database when the
      static method are not on the classpath. You can create an SQL/PSM
      procedure which calls all the SQL/JRT functions and procedures in your
      database. The calls should have the necessary dummy arguments. This
      procedure will fail to be created when the referenced methods are not
      accessible and will return "Error in script file". There is no need ever
      to execute the procedure. However, to avoid accidental use, you can
      ensure that it does not execute the SQL/JRT routines by adding a line
      such as <code class="literal">IF TRUE THEN RETURN;</code> before any references to
      the SQL/JRT routines.</p>
</div>
</div>
<div class="section" title="User Defined Aggregate Functions">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="src_aggregate_functions"></a>User Defined Aggregate Functions</h2>
</div>
</div>
</div>
<p>HyperSQL adds an extension to the SQL Standard to allow user-defined
    aggregate functions. A user-defined aggregate function has a single
    parameter when it is used in SQL statements. Unlike the predefined
    aggregate functions, the keyword DISTINCT cannot be used when a user
    defined aggregate function is invoked. Like all user-defined functions, an
    aggregate function belongs to a schema and can be polymorphic (using
    multiple function definitions with the same name but different parameter
    types).</p>
<p>A user defined aggregate function can be used in SQL statements
    where a predefined aggregate function is allowed.</p>
<div class="section" title="Definition of Aggregate Functions">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="src_aggregate_function_definition"></a>Definition of Aggregate Functions</h3>
</div>
</div>
</div>
<p>An aggregate function is always defined with 4 parameters. The
      first parameter is the parameter that is used when the function is
      invoked in SQL statements, the rest of the parameter are invisible to
      the invoking SQL statement. The type of the first parameter is user
      defined. The type of the second parameter must be BOOLEAN. The third and
      fourth parameters have user defined types and must be defined as INOUT
      parameters. The defined return type of the function determines the type
      of the value returned when the function is invoked.</p>
<a name="N133BD" class="indexterm"></a>
<p>
<span class="bold"><strong>CREATE AGGREGATE
      FUNCTION</strong></span>
</p>
<p>
<span class="emphasis"><em>user defined aggregate function
      definition</em></span>
</p>
<p>Aggregate function definition is similar to normal function
      definition and has the mandatory <code class="literal">&lt;returns
      clause&gt;</code>. The BNF is given below.</p>
<p>
<code class="literal">&lt;user defined aggregate function&gt; ::= CREATE
      AGGREGATE FUNCTION &lt;schema qualified routine name&gt; &lt;SQL
      aggregate parameter declaration list&gt; &lt;returns clause&gt;
      &lt;routine characteristics&gt; &lt;routine body&gt;</code>
</p>
<p>The parameter declaration list BNF is given below. The type of the
      first parameter is used when the function is invoked as part of an SQL
      statement. When multiple versions of a function are required, each
      version will have the first parameter of a different type.</p>
<p>
<code class="literal">&lt;SQL aggregate declaration list&gt; ::= &lt;left
      paren&gt; [IN] [ &lt;SQL parameter name&gt; ] &lt;parameter type&gt;
      &lt;comma&gt; [IN] [ &lt;SQL parameter name&gt; ] BOOLEAN &lt;comma&gt;
      INOUT [ &lt;SQL parameter name&gt; ] &lt;parameter type&gt;
      &lt;comma&gt; INOUT [ &lt;SQL parameter name&gt; ] &lt;parameter
      type&gt; &lt;right paren&gt;</code>
</p>
<p>The return type is user defined. This is the type of the resulting
      value when the function is called. Usually an aggregate function is
      defined with CONTAINS SQL, as it normally does not read the data in
      database tables, but it is possible to define the function with READS
      SQL DATA and access the database tables.</p>
<p>When a SQL statement that uses the aggregate function is executed,
      HyperSQL invokes the aggregate function, with all the arguments set,
      once per each row in order to compute the values. Finally, it invokes
      the function once more to return the final result.</p>
<p>In the computation phase, the first argument is the value of the
      user argument as specified in the SQL statement, computed for the
      current row. The second argument is the boolean FALSE. The third and
      fourth argument values can have any type and are initially null, but
      they can be updated in the body of the function during each invocation.
      The third and fourth arguments act as registers and hold their values
      between invocations. The return value of the function is ignored during
      the computation phase (when the second parameter is FALSE).</p>
<p>After the computation phase, the function is invoked once more to
      get the final result. In this invocation, the first argument is NULL and
      the second argument is boolean TRUE. The third and fourth arguments hold
      the values they held at the end of the last invocation. The value
      returned by the function in this invocation is used as the result of the
      aggregate function computation in the invoking SQL statement. In SQL
      queries with GROUP BY, the call sequence is repeated separately for each
      separate group.</p>
</div>
<div class="section" title="SQL PSM Aggregate Functions">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="src_psm_aggregate_functions"></a>SQL PSM Aggregate Functions</h3>
</div>
</div>
</div>
<p>The example below features a user defined version of the Standard
      <code class="literal">AVG(&lt;value expression&gt;)</code> aggregate function for
      INTEGER input and output types. This function behaves differently from
      the Standard AVG function as it returns 0 when all the input values are
      null.</p>
<pre class="programlisting"> CREATE AGGREGATE FUNCTION udavg(IN x INTEGER, IN flag BOOLEAN, INOUT addup BIGINT, INOUT counter INT)
   RETURNS INTEGER
   CONTAINS SQL
   BEGIN ATOMIC
     IF flag THEN
       RETURN addup / counter;
     ELSE
       SET counter = COALESCE(counter, 0) + 1;
       SET addup = COALESCE(addup, 0) || COALESCE(x, 0);
       RETURN NULL;
     END IF;
   END

</pre>
<p>The user defined aggregate function is used in a select statement
      in the example below. Only the first parameter is visible and utilised
      in the select statement.</p>
<pre class="programlisting"> SELECT udavg(id) FROM customers GROUP BY lastname;</pre>
<p>In the example below, the function returns an array that contains
      all the values passed for the aggregated column. For use with longer
      arrays, you can optimise the function by defining a larger array in the
      first iteration, and using the TRIM_ARRAY function on the RETURN to cut
      the array to size. This function is similar to the built-in ARRAY_AGG
      function</p>
<pre class="programlisting"> CREATE AGGREGATE FUNCTION array_aggregate(IN val VARCHAR(100), IN flag boolean, INOUT buffer VARCHAR(100) ARRAY, INOUT counter INT)
   RETURNS VARCHAR(100) ARRAY
   CONTAINS SQL
   BEGIN ATOMIC
     IF flag THEN
       RETURN buffer;
     ELSE
       IF val IS NULL THEN RETURN NULL; END IF;
       IF counter IS NULL THEN SET counter = 0; END IF;
       SET counter = counter + 1;
       IF counter = 1 THEN SET buffer = ARRAY[val];
       ELSE SET buffer[counter] = val; END IF;
       RETURN NULL;
     END IF;
   END
</pre>
<p>The tables and data for the select statement below are created
      with the DatabaseManager or DatabaseManagerSwing GUI apps. (You can find
      the SQL in the TestSelf.txt file in the zip). Part of the output is
      shown. Each row of the output includes an array containing the values
      for the invoices for each customer.</p>
<pre class="programlisting"> SELECT ID, FIRSTNAME, LASTNAME, ARRAY_AGGREGATE(CAST(INVOICE.TOTAL AS VARCHAR(100))) 
   FROM customer JOIN INVOICE ON ID =CUSTOMERID
   GROUP BY ID, FIRSTNAME, LASTNAME

 11 Susanne   Karsen    ARRAY['3988.20']                               
 12 John      Peterson  ARRAY['2903.10','4382.10','4139.70','3316.50'] 
 13 Michael   Clancy    ARRAY['6525.30']                               
 14 James     King      ARRAY['3665.40','905.10','498.00']             
 18 Sylvia    Clancy    ARRAY['634.20','4883.10']                      
 20 Bob       Clancy    ARRAY['3414.60','744.60']
</pre>
<p>In the example below, the function returns a string that contains
      the comma-separated list of all the values passed for the aggregated
      column. This function is similar to the built in GROUP_CONCAT
      function.</p>
<pre class="programlisting"> CREATE AGGREGATE FUNCTION group_concatenate
     (IN val VARCHAR(100), IN flag BOOLEAN, INOUT buffer VARCHAR(1000), INOUT counter INT)
     RETURNS VARCHAR(1000)
     CONTAINS SQL
   BEGIN ATOMIC
     IF FLAG THEN
       RETURN BUFFER;
     ELSE
       IF val IS NULL THEN RETURN NULL; END IF;
       IF buffer IS NULL THEN SET BUFFER = ''; END IF;
       IF counter IS NULL THEN SET COUNTER = 0; END IF;
       IF counter &gt; 0 THEN SET buffer = buffer || ','; END IF;
       SET buffer = buffer + val;
       SET counter = counter + 1;
       RETURN NULL;
     END IF;
   END
</pre>
<p>The same tables and data as for the previous example is used. Part
      of the output is shown. Each row of the output is a comma-separated list
      of names.</p>
<pre class="programlisting"> SELECT group_concatenate(firstname || ' ' || lastname) FROM customer GROUP BY lastname
  
 Laura Steel,John Steel,John Steel,Robert Steel                                   
 Robert King,Robert King,James King,George King,Julia King,George King            
 Robert Sommer,Janet Sommer                                                       
 Michael Smith,Anne Smith,Andrew Smith                                            
 Bill Fuller,Anne Fuller                                                          
 Laura White,Sylvia White                                                         
 Susanne Clancy,Michael Clancy,Sylvia Clancy,Bob Clancy,Susanne Clancy,John Clancy
</pre>
</div>
<div class="section" title="Java Aggregate Functions">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="src_jrt_aggregate_functions"></a>Java Aggregate Functions</h3>
</div>
</div>
</div>
<p>A Java aggregate function is defined similarly to PSM functions,
      apart from the routine body, which is defined as <code class="literal">EXTERNAL NAME
      ...</code> The Java function signature must follow the rules for both
      nullable and INOUT parameters, therefore:</p>
<p>No argument is defined as a primitive or primitive array type.
      This allows nulls to be passed to the function. The second and third
      arguments must be defined as arrays of the JDBC non-primitive types
      listed in the table in the previous section.</p>
<p>In the example below, a user-defined aggregate function for
      geometric mean is defined.</p>
<pre class="programlisting"> CREATE AGGREGATE FUNCTION geometric_mean(IN val DOUBLE, IN flag BOOLEAN, INOUT register DOUBLE, INOUT counter INT)
     RETURNS DOUBLE
     NO SQL
     LANGUAGE JAVA
     EXTERNAL NAME 'CLASSPATH:org.hsqldb.test.Test01.geometricMean'
</pre>
<p>The Java function definition is given below:</p>
<pre class="programlisting"> public static Double geometricMean(Double in, Boolean flag,
         Double[] register, Integer[] counter) {
     if (flag) {
         if (register[0] == null) { return null; }
         double a = register[0].doubleValue();
         double b = 1 / (double) counter[0];
         return Double.valueOf(java.lang.Math.pow(a, b));
     }
     if (in == null) { return null; }
     if (in.doubleValue() == 0) { return null; }
     if (register[0] == null) {
         register[0] = in;
         counter[0]  = Integer.valueOf(1);
     } else {
         register[0] = Double.valueOf(register[0].doubleValue() * in.doubleValue());
         counter[0] = Integer.valueOf(counter[0].intValue() + 1);
     }
     return null;
 }
</pre>
<p>In a select statement, the function is used exactly like the
      built-in aggregate functions:</p>
<pre class="programlisting"> SELECT geometric_mean(age) FROM  FROM customer
</pre>
</div>
</div>
</div>
<div class="chapter" title="Chapter&nbsp;9.&nbsp;Triggers">
<div class="titlepage">
<div>
<div>
<h2 class="title">
<a name="triggers-chapt"></a>Chapter&nbsp;9.&nbsp;Triggers</h2>
</div>
<div>
<div class="authorgroup">
<div class="author">
<h3 class="author">
<span class="firstname">Fred</span> <span class="surname">Toussi</span>
</h3>
<div class="affiliation">
<span class="orgname">The HSQL Development Group<br>
</span>
</div>
</div>
</div>
</div>
<div>
<p class="releaseinfo">$Revision: 3042 $</p>
</div>
<div>
<div class="legalnotice" title="Legal Notice">
<a name="N13438"></a>
<p>Copyright 2010-2012 Fred Toussi. Permission is granted to
      distribute this document without any alteration under the terms of the
      HSQLDB license. Additional permission is granted to the HSQL Development
      Group to distribute this document with or without alterations under the
      terms of the HSQLDB license.</p>
</div>
</div>
<div>
<p class="pubdate">2014-02-13 18:21:41-0500</p>
</div>
</div>
</div>
<div class="toc">
<p>
<b>Table of Contents</b>
</p>
<dl>
<dt>
<span class="section"><a href="#trc_overview">Overview</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#trc_before_triggers">BEFORE Triggers</a></span>
</dt>
<dt>
<span class="section"><a href="#trc_after_triggers">AFTER Triggers</a></span>
</dt>
<dt>
<span class="section"><a href="#trc_instead_of_triggers">INSTEAD OF Triggers</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#trc_trigger_props">Trigger Properties</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#trc_trigger_event">Trigger Event</a></span>
</dt>
<dt>
<span class="section"><a href="#trc_trigger_granularity">Granularity</a></span>
</dt>
<dt>
<span class="section"><a href="#trc_trigger_action_time">Trigger Action Time</a></span>
</dt>
<dt>
<span class="section"><a href="#trc_row_references">References to Rows</a></span>
</dt>
<dt>
<span class="section"><a href="#trc_trigger_condition">Trigger Condition</a></span>
</dt>
<dt>
<span class="section"><a href="#trc_trigger_action_sql">Trigger Action in SQL</a></span>
</dt>
<dt>
<span class="section"><a href="#trc_trigger_action_java">Trigger Action in Java</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#trc_trigger_creation">Trigger Creation</a></span>
</dt>
</dl>
</div>
<div class="section" title="Overview">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="trc_overview"></a>Overview</h2>
</div>
</div>
</div>
<p>Trigger functionality first appeared in SQL:1999. Triggers embody
    the <span class="emphasis"><em>live database</em></span> concept, where changes in SQL data
    can be monitored and acted upon. This means each time a DELETE, UPDATE or
    INSERT is performed, additional actions are taken by the declared
    triggers. SQL Standard triggers are <em class="glossterm">imperative</em>
    while the <em class="glossterm">relational</em> aspects of SQL are
    <em class="glossterm">declarative</em>. Triggers allow performing an arbitrary
    transformation of data that is being updated or inserted, or to prevent
    insert, updated or deletes, or to perform additional operations.</p>
<p>Some bad examples of SQL triggers in effect enforce an &ldquo;integrity
    constraint&rdquo; which would better be expressed as a CHECK constraint. A
    trigger that causes an exception if the value inserted in a column is
    negative is such an example. A check constraint that declares
    <code class="literal">CHECK VALUE &gt;= 0</code> (declarative) is a better way of
    expressing an integrity constraint than a trigger that throws an exception
    if the same condition is false.</p>
<p>Usage constraints cannot always be expressed by SQL&rsquo;s integrity
    constraint statements. Triggers can enforce these constraints. For
    example, it is not possible to use a check constraint to prevent inserts
    or deletes on weekends. A trigger can be used to enforce the time when
    each operation is allowed.</p>
<p>A trigger is declared to activate when an UPDATE, INSERT or
    DELETE action is performed on a table. These actions may be direct or
    indirect. Indirect actions may arise from CASCADE actions of FOREIGN KEY
    constraints, or from data change statements performed on a VIEW that is
    based on the table that in.</p>
<p>It is possible to declare multiple triggers on a single table.
    The triggers activate one by one according to the order in which they were
    defined. HyperSQL supports an extension to the CREATE TRIGGER statement,
    which allows the user to specify the execution order of the new
    trigger.</p>
<p>A row level trigger allows access to the deleted or inserted
    rows. For UPDATE actions there is both an old and new version of each row.
    A trigger can be specified to activate before or after the action has been
    performed.</p>
<div class="section" title="BEFORE Triggers">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="trc_before_triggers"></a>BEFORE Triggers</h3>
</div>
</div>
</div>
<p>A trigger that is declared as BEFORE DELETE cannot modify the
      deleted row. In other words, it cannot decide to delete a different row
      by changing the column values of the row. A trigger that is declared as
      BEFORE INSERT and BEFORE UPDATE can modify the values that are inserted
      into the database. For example, a badly formatted string can be cleaned
      up by a trigger before INSERT or UPDATE.</p>
<p>BEFORE triggers cannot modify the other tables of the database.
      All BEFORE triggers can veto the action by throwing an
      exception.</p>
<p>Because BEFORE triggers can modify the inserted or updated
      rows, all constraint checks are performed after the execution of the
      BEFORE triggers. The checks include NOT NULL constraints, length of
      strings, CHECK constraints, and FOREIGN key constraints.</p>
</div>
<div class="section" title="AFTER Triggers">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="trc_after_triggers"></a>AFTER Triggers</h3>
</div>
</div>
</div>
<p>AFTER triggers can also perform additional data changes, for
      example inserting an additional row into a different table for data
      audits. These triggers cannot modify the rows that have been modified by
      the INSERT or UPDATE action.</p>
</div>
<div class="section" title="INSTEAD OF Triggers">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="trc_instead_of_triggers"></a>INSTEAD OF Triggers</h3>
</div>
</div>
</div>
<p>A trigger that is declared on a VIEW, is an INSTEAD OF trigger.
      This term means when an INSERT, UPDATE or DELETE statement is executed
      with the view as the target, the trigger action is all that is
      performed, and no further data change takes place on the view. The
      trigger action can include all the statements that are necessary to
      change the data in the tables that underlie the view, or even other
      tables, such as audit tables. With the use of INSTEAD OF triggers a
      read-only view can effectively become updatable or
      insertable-into.</p>
</div>
</div>
<div class="section" title="Trigger Properties">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="trc_trigger_props"></a>Trigger Properties</h2>
</div>
</div>
</div>
<p>A trigger is declared on a specific table or view. Various trigger
    properties determine when the trigger is executed and how.</p>
<div class="section" title="Trigger Event">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="trc_trigger_event"></a>Trigger Event</h3>
</div>
</div>
</div>
<p>The trigger event specifies the type of SQL statement that causes
      the trigger to execute. Each trigger is specified to execute when an
      INSERT, DELETE or UPDATE takes place.</p>
<p>The event can be filtered by two separate means. For all triggers,
      the WHEN clause can specify a condition against the rows that are the
      subject of the trigger, together with the data in the database. For
      example, a trigger can activate when the size of a table becomes larger
      than a certain amount. Or it can activate when the values in the rows
      being modified satisfy certain conditions.</p>
<p>An UPDATE trigger can be declared to execute only when certain
      columns are the subject of an update statement. For example, a trigger
      declared as AFTER UPDATE OF (datecolumn) will activate only when the
      UPDATE statement that is executed includes the column, datecolumn, as
      one of the columns specified in its SET statements.</p>
</div>
<div class="section" title="Granularity">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="trc_trigger_granularity"></a>Granularity</h3>
</div>
</div>
</div>
<p>A statement level trigger is performed once for the executed SQL
      statement and is declared as FOR EACH STATEMENT.</p>
<p>A row level trigger is performed once for each row that is
      modified during the execution of an SQL statement and is declared as FOR
      EACH ROW. Note that an SQL statement can INSERT, UPDATE or DELETE zero
      or more rows.</p>
<p>If a statement does not apply to any row, then the trigger is not
      executed.</p>
<p>If FOR EACH ROW or FOR EACH STATEMENT is not specified, then the
      default is FOR EACH STATEMENT.</p>
<p>The granularity dictates whether the REFERENCING clause can
      specify OLD ROW, NEW ROW, or OLD TABLE, NEW TABLE.</p>
<p>A trigger declared as FOR EACH STATEMENT can only be an AFTER
      trigger.</p>
</div>
<div class="section" title="Trigger Action Time">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="trc_trigger_action_time"></a>Trigger Action Time</h3>
</div>
</div>
</div>
<p>A trigger is executed BEFORE, AFTER or INSTEAD OF the trigger
      event.</p>
<p>INSTEAD OF triggers are allowed only when the trigger is declared
      on a VIEW. With this type of trigger, the event (SQL statement) itself
      is not executed, only the trigger.</p>
<p>BEFORE or AFTER triggers are executed just before or just after
      the execution of the event. For example, just before a row is inserted
      into a table, the BEFORE trigger is activated, and just after the row is
      inserted, the AFTER trigger is executed.</p>
<p>BEFORE triggers can modify the row that is being inserted or
      updated. AFTER triggers cannot modify rows. They are usually used to
      perform additional operations, such as inserting rows into other
      tables.</p>
<p>A trigger declared as FOR EACH STATEMENT can only be an AFTER
      trigger.</p>
</div>
<div class="section" title="References to Rows">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="trc_row_references"></a>References to Rows</h3>
</div>
</div>
</div>
<p>If the old rows or new rows are referenced in the SQL statements
      in the trigger action, they must have names. The REFERENCING clause is
      used to give names to the old and new rows. The clause, REFERENCING OLD
      | NEW TABLE is used for statement level triggers. The clause,
      REFERENCING OLD | NEW ROW is used for row level triggers. If the old
      rows or new rows are referenced in the SQL statements in the trigger
      action, they must have names. In the SQL statements, the columns of the
      old or new rows are qualified with the specified names.</p>
</div>
<div class="section" title="Trigger Condition">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="trc_trigger_condition"></a>Trigger Condition</h3>
</div>
</div>
</div>
<p>The WHEN clause can specify a condition for the columns of the row
      that is being changed. Using this clause you can simply avoid
      unnecessary trigger activation for rows that do not need it.</p>
<p>For UPDATE trigger, you can specify a list of columns of the
      table. If a list of columns is specified, then if the UPDATE statement
      does not change the columns with SET clauses, then the trigger is not
      activated at all.</p>
</div>
<div class="section" title="Trigger Action in SQL">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="trc_trigger_action_sql"></a>Trigger Action in SQL</h3>
</div>
</div>
</div>
<p>The trigger action specifies what the trigger does when it is
      activated. This is usually written as one or more SQL statements.</p>
<p>When a row level trigger is activated, there is an OLD ROW, or a
      NEW ROW, or both. An INSERT statement supplies a NEW ROW row to be
      inserted into a table. A DELETE statement supplies an OLD ROW be
      deleted. An UPDATE statement supplies both OLD ROW and NEW ROW that
      represent the updated rows before and after the update. The REFERENCING
      clause gives names to these rows, so that the rows can be referenced in
      the trigger action.</p>
<p>In the example below, a name is given to the NEW ROW and it is
      used both in the WHEN clause and in the trigger action SQL to insert a
      row into a triglog table after each row insert into the testtrig
      table.</p>
<pre class="programlisting"> CREATE TRIGGER trig AFTER INSERT ON testtrig 
   REFERENCING NEW ROW AS newrow
   FOR EACH ROW WHEN (newrow.id &gt; 1)
   INSERT INTO TRIGLOG VALUES (newrow.id, newrow.data, 'inserted')
</pre>
<p>In the example blow, the trigger code modifies the updated data if
      a condition is true. This type of trigger is useful when the application
      does not perform the necessary checks and modifications to data. The
      statement block that starts with BEGIN ATOMIC is similar to an SQL/PSM
      block and can contain all the SQL statements that are allowed in an
      SQL/PSM block.</p>
<pre class="programlisting"> CREATE TRIGGER t BEFORE UPDATE ON customer
   REFERENCING NEW AS newrow FOR EACH ROW
   BEGIN ATOMIC
     IF LENGTH(newrow.firstname) &gt; 10 THEN
       SET newrow.firstname = LOWER(newrow.firstname);
     END IF;
   END
</pre>
</div>
<div class="section" title="Trigger Action in Java">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="trc_trigger_action_java"></a>Trigger Action in Java</h3>
</div>
</div>
</div>
<p>A trigger action can be written as a Java class that implements
      the <code class="classname">org.hsqldb.Trigger</code> interface. This interface
      has a single method which is called when the trigger is activated,
      either before or after the event. When the method is called by the
      engine, it supplies the type of trigger as an int value defined by the
      interface(as type argument), the name of the trigger (as trigName
      argument), the name of the table (as tabName argument), the OLD ROW (as
      oldRow argument) and the NEW ROW (as newRow argument). The oldRow
      argument is null for row level INSERT triggers. The newRow argument is
      null for row level DELETE triggers. For table level triggers, both
      arguments are null (that is, there is no access to the data). The
      triggerType argument is one of the constants in the org.hsqldb.Trigger
      interface which indicate the type of trigger, for example,
      INSERT_BEFORE_ROW or UPDATE_AFTER_ROW.</p>
<p>The Java class for the trigger can be reused for several triggers
      on different tables. The method code can distinguish between the
      different tables and triggers using the supplied arguments and take
      appropriate action.</p>
<pre class="programlisting"> fire (int triggerType, String name, String table, Object row1[], Object row2[])
</pre>
<p>The Java method for a synchronous trigger (see below) can modify
      the values in newRow2 in a BEFORE trigger. Such modifications are
      reflected in the row that is being inserted or updated. Any other
      modifications are ignored by the engine.</p>
<p>A Java trigger that uses an instance of
      <code class="classname">org.hsqldb.Trigger</code> has two forms, synchronous, or
      asynchronous (immediate or queued). By default, or when QUEUE 0 is
      specified, the action is performed immediately by calling the Java
      method. This is similar to SQL trigger actions.</p>
<p>When QUEUE n is specified with n larger than 0, the engine uses a
      separate thread to execute the Java method, using a queue with the size
      n. For certain applications, such as real-time systems this allows
      asynchronous notifications to be sent by the trigger event, without
      introducing delays in the engine. With asynchronous triggers, an extra
      parameter, NOWAIT can be used in trigger definition. This overcomes the
      queue full condition. In this mode, old calls that are still in the
      queue are discarded one by one and replaced with new calls.</p>
<p>Java row level triggers that are declared with BEFORE trigger
      action time can modify the row data. Triggers with AFTER trigger action
      time can modify the database, e.g. insert new rows. If the trigger needs
      to access the database, the same method as in Java Language Routines
      SQL/JRT can be used. The Java code should connect to the URL
      <code class="literal">"jdbc:default:connection"</code> and use this connection to
      access the database.</p>
<p>For sample trigger classes and test code see,
      <code class="classname">org.hsqldb.sample.TriggerSample</code>,
      <code class="classname">org.hsqldb.test.TestTriggers</code>,
      <code class="classname">org.hsqldb.test.TriggerClass</code> and the associated
      text script <code class="filename">TestTriggers.txt</code> in the
      <code class="literal">/testrun/hsqldb/</code> directory. In the example below, the
      trigger is activated only if the update statement includes SET clauses
      that modify any of the specified columns (c1, c2, c3). Furthermore, the
      trigger is not activated if the c2 column in the updated row is
      null.</p>
<pre class="programlisting"> CREATE TRIGGER TRIGBUR BEFORE UPDATE OF c1, c2, c3 ON testtrig 
   referencing NEW ROW AS newrow
   FOR EACH ROW WHEN (newrow.c2 IS NOT NULL)
   CALL "org.hsqldb.test.TriggerClass"
</pre>
<p>Java functions can be called from an SQL trigger. So it is
      possible to define the Java function to perform any external
      communication that are necessary for the trigger, and use SQL code for
      checks and alterations to data.</p>
<pre class="programlisting"> CREATE TRIGGER t BEFORE UPDATE ON customer
   REFERENCING NEW AS newrow FOR EACH ROW
   BEGIN ATOMIC
     IF LENGTH(newrow.firstname) &gt; 10 THEN
       CALL my_java_function(newrow.firstname, newrow.lastname);
     END IF;
   END
</pre>
</div>
</div>
<div class="section" title="Trigger Creation">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="trc_trigger_creation"></a>Trigger Creation</h2>
</div>
</div>
</div>
<a name="N134F2" class="indexterm"></a>
<p>
<span class="bold"><strong>CREATE TRIGGER</strong></span>
</p>
<p>
<span class="emphasis"><em>trigger definition</em></span>
</p>
<p>
<code class="literal">&lt;trigger definition&gt; ::= CREATE TRIGGER
    &lt;trigger name&gt; &lt;trigger action time&gt; &lt;trigger event&gt; ON
    &lt;table name&gt; [BEFORE &lt;other trigger name&gt;] [ REFERENCING
    &lt;transition table or variable list&gt; ] &lt;triggered
    action&gt;</code>
</p>
<p>
<code class="literal">&lt;trigger action time&gt; ::= BEFORE | AFTER | INSTEAD
    OF</code>
</p>
<p>
<code class="literal">&lt;trigger event&gt; ::= INSERT | DELETE | UPDATE [ OF
    &lt;trigger column list&gt; ]</code>
</p>
<p>
<code class="literal">&lt;trigger column list&gt; ::= &lt;column name
    list&gt;</code>
</p>
<p>
<code class="literal">&lt;triggered action&gt; ::= [ FOR EACH { ROW |
    STATEMENT } ] [ &lt;triggered when clause&gt; ] &lt;triggered SQL
    statement&gt;</code>
</p>
<p>
<code class="literal">&lt;triggered when clause&gt; ::= WHEN &lt;left
    paren&gt; &lt;search condition&gt; &lt;right paren&gt;</code>
</p>
<p>
<code class="literal">&lt;triggered SQL statement&gt; ::= &lt;SQL procedure
    statement&gt; | BEGIN ATOMIC { &lt;SQL procedure statement&gt;
    &lt;semicolon&gt; }... END | [QUEUE &lt;integer literal&gt;] [NOWAIT] CALL
    &lt;HSQLDB trigger class FQN&gt;</code>
</p>
<p>
<code class="literal">&lt;transition table or variable list&gt; ::=
    &lt;transition table or variable&gt;...</code>
</p>
<p>
<code class="literal">&lt;transition table or variable&gt; ::= OLD [ ROW ] [
    AS ] &lt;old transition variable name&gt; | NEW [ ROW ] [ AS ] &lt;new
    transition variable name&gt; | OLD TABLE [ AS ] &lt;old transition table
    name&gt; | NEW TABLE [ AS ] &lt;new transition table
    name&gt;</code>
</p>
<p>
<code class="literal">&lt;old transition table name&gt; ::= &lt;transition
    table name&gt;</code>
</p>
<p>
<code class="literal">&lt;new transition table name&gt; ::= &lt;transition
    table name&gt;</code>
</p>
<p>
<code class="literal">&lt;transition table name&gt; ::=
    &lt;identifier&gt;</code>
</p>
<p>
<code class="literal">&lt;old transition variable name&gt; ::= &lt;correlation
    name&gt;</code>
</p>
<p>
<code class="literal">&lt;new transition variable name&gt; ::= &lt;correlation
    name&gt;</code>
</p>
<p>Trigger definition is a relatively complex statement. The
    combination of <code class="literal">&lt;trigger action time&gt;</code> and
    <code class="literal">&lt;trigger event&gt;</code> determines the type of the
    trigger. Examples include BEFORE DELETE, AFTER UPDATE, INSTEAD OF INSERT.
    If the optional <code class="literal">[ OF &lt;trigger column list&gt; ]</code> is
    specified for an UPDATE trigger, then the trigger is activated only if one
    of the columns that is in the <code class="literal">&lt;trigger column
    list&gt;</code> is specified in the UPDATE statement that activates the
    trigger.</p>
<p>If a trigger is <code class="literal">FOR EACH ROW</code>, which is the
    default option, then the trigger is activated for each row of the table
    that is affected by the execution of an SQL statement. Otherwise, it is
    activated once only per statement execution. For <code class="literal">FOR EACH
    ROW</code> triggers, there is an OLD and NEW state for each row. For
    UPDATE triggers, both OLD and NEW states exist, representing the row
    before the update, and after the update. For DELETE, triggers, there is
    only an OLD state. For INSERT triggers, there is only the NEW state. If a
    trigger is <code class="literal">FOR EACH STATEMENT</code>, then a transient table
    is created containing all the rows for the OLD state and another transient
    table is created for the NEW state.</p>
<p>The <code class="literal">[ REFERENCING &lt;transition table or variable&gt;
    ]</code> is used to give a name to the OLD and NEW data row or table.
    This name can be referenced in the <code class="literal">&lt;SQL procedure
    statement&gt;</code> to access the data.</p>
<p>The optional <code class="literal">&lt;triggered when clause&gt;</code> is
    a search condition, similar to the search condition of a DELETE or UPDATE
    statement. If the search condition is not TRUE for a row, then the trigger
    is not activated for that row.</p>
<p>The <code class="literal">&lt;SQL procedure statement&gt;</code> is limited
    to INSERT, DELETE, UPDATE and MERGE statements.</p>
<p>The <code class="literal">&lt;HSQLDB trigger class FQN&gt;</code> is a
    delimited identifier that contains the fully qualified name of a Java
    class that implements the <code class="classname">org.hsqldb.Trigger</code>
    interface.</p>
<p>Early releases of HyperSQL version 2.0 do not allow the use of
    OLD TABLE or NEW TABLE in statement level triggers.</p>
<a name="N1355D" class="indexterm"></a>
<p>
<span class="bold"><strong>TRIGGERED SQL
    STATEMENT</strong></span>
</p>
<p>
<span class="emphasis"><em>triggered SQL statement</em></span>
</p>
<p>
<code class="literal">The &lt;triggered SQL statement&gt;</code> has three
    forms.</p>
<p>The first form is a single SQL procedure statement. This
    statement can reference the OLD ROW and NEW ROW variables. For example, it
    can reference these variables and insert a row into a separate
    table.</p>
<p>The second form is enclosed in a BEGIN ... END block and can
    include one or more SQL procedure statements. In BEFORE triggers, you can
    include SET statements to modify the inserted or updated rows. In AFTER
    triggers, you can include INSERT, DELETE and UPDATE statements to change
    the data in other database tables. SELECT and CALL statements are allowed
    in BEFORE and AFTER triggers. CALL statements in BEFORE triggers should
    not modify data.</p>
<p>The third form specifies a call to a Java method.</p>
<p>Two examples of a trigger with a block are given below. The block
    can include elements discussed in the <a class="link" href="#sqlroutines-chapt" title="">SQL-Invoked Routines</a> chapter, including
    local variables, loops and conditionals. You can also raise an exception
    in such blocks in order to terminate the execution of the SQL statement
    that caused the trigger to execute.</p>
<pre class="programlisting">/* the trigger throws an exception if a customer with the given last name already exists */
 CREATE TRIGGER trigone BEFORE INSERT ON customer 
   REFERENCING NEW ROW AS newrow
   FOR EACH ROW WHEN (newrow.id &gt; 100)
   BEGIN ATOMIC
     IF EXISTS (SELECT * FROM CUSTOMER WHERE CUSTOMER.LASTNAME = NEW.LASTNAME) THEN
       SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = 'already exists';
     END IF;
   END
</pre>
<pre class="programlisting">/* for each row inserted into the target, the trigger insert a row into the table used for logging */
 CREATE TRIGGER trig AFTER INSERT ON testtrig 
   BEFORE othertrigger  
   REFERENCING NEW ROW AS newrow
   FOR EACH ROW WHEN (newrow.id &gt; 1)
   BEGIN ATOMIC
     INSERT INTO triglog VALUES (newrow.id, newrow.data, 'inserted');
     /* more statements can be included */
   END
</pre>
<p></p>
<a name="N1357F" class="indexterm"></a>
<p>
<span class="bold"><strong>TRIGGER EXECUTION
    ORDER</strong></span>
</p>
<p>
<span class="emphasis"><em>trigger execution order</em></span>
</p>
<p>
<code class="literal">&lt;trigger execution order&gt; ::= BEFORE &lt;other
    trigger name&gt;</code>
</p>
<p>HyperSQL extends the SQL Standard to allow the order of execution
    of a trigger to be specified by using [BEFORE &lt;other trigger name&gt;]
    in the definition. The newly defined trigger will be executed before the
    specified other trigger. If this clause is not used, the new trigger is
    executed after all the previously defined triggers of the same scope
    (BEFORE, AFTER, EACH ROW, EACH STATEMENT).</p>
<a name="N13590" class="indexterm"></a>
<p>
<span class="bold"><strong>DROP TRIGGER</strong></span>
</p>
<p>
<span class="emphasis"><em>drop trigger statement</em></span>
</p>
<p>
<code class="literal">&lt;drop trigger statement&gt; ::= DROP TRIGGER
    &lt;trigger name&gt;</code>
</p>
<p>Destroy a trigger.</p>
</div>
</div>
<div class="chapter" title="Chapter&nbsp;10.&nbsp;Built In Functions">
<div class="titlepage">
<div>
<div>
<h2 class="title">
<a name="builtinfunctions-chapt"></a>Chapter&nbsp;10.&nbsp;Built In Functions</h2>
</div>
<div>
<div class="authorgroup">
<div class="author">
<h3 class="author">
<span class="firstname">Fred</span> <span class="surname">Toussi</span>
</h3>
<div class="affiliation">
<span class="orgname">The HSQL Development Group<br>
</span>
</div>
</div>
</div>
</div>
<div>
<p class="releaseinfo">$Revision: 5310 $</p>
</div>
<div>
<div class="legalnotice" title="Legal Notice">
<a name="N135C5"></a>
<p>Copyright 2010-2012 Fred Toussi. Permission is granted to
      distribute this document without any alteration under the terms of the
      HSQLDB license. Additional permission is granted to the HSQL Development
      Group to distribute this document with or without alterations under the
      terms of the HSQLDB license.</p>
</div>
</div>
<div>
<p class="pubdate">2014-02-13 18:21:41-0500</p>
</div>
</div>
</div>
<div class="toc">
<p>
<b>Table of Contents</b>
</p>
<dl>
<dt>
<span class="section"><a href="#bfc_overview">Overview</a></span>
</dt>
<dt>
<span class="section"><a href="#bfc_string_binary_functions">String and Binary String Functions</a></span>
</dt>
<dt>
<span class="section"><a href="#bfc_numeric_functions">Numeric Functions</a></span>
</dt>
<dt>
<span class="section"><a href="#bfc_datetime_functions">Date Time and Interval Functions</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#bfc_timezone_functions">Functions to Report the Time Zone.</a></span>
</dt>
<dt>
<span class="section"><a href="#bfc_current_datetime">Functions to Report the Current Datetime</a></span>
</dt>
<dt>
<span class="section"><a href="#bfc_extract_datetime">Functions to Extract an Element of a Datetime</a></span>
</dt>
<dt>
<span class="section"><a href="#bfc_datetime_arithmetic">Functions for Datetime Arithmetic</a></span>
</dt>
<dt>
<span class="section"><a href="#bfc_datetime_format">Functions to Convert or Format a Datetime</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#bfc_array_functions">Array Functions</a></span>
</dt>
<dt>
<span class="section"><a href="#bfc_general_functions">General Functions</a></span>
</dt>
<dt>
<span class="section"><a href="#bfc_system_functions">System Functions</a></span>
</dt>
</dl>
</div>
<div class="section" title="Overview">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="bfc_overview"></a>Overview</h2>
</div>
</div>
</div>
<p>HyperSQL supports a wide range of built-in functions and allows
    user-defined functions written in SQL and Java languages. User-defined
    functions are covered in the <a class="link" href="#sqlroutines-chapt" title="Chapter&nbsp;8.&nbsp;SQL-Invoked Routines">SQL-Invoked Routines</a> chapter. If a built-in function is
    not available, you can write your own using procedural SQL or Java.</p>
<p>Built-in aggregate functions such as <code class="literal">SUM,</code>
    <code class="literal">MAX</code>, <code class="literal">ARRAY_AGG</code>,
    <code class="literal">GROUP_CONCAT</code> are covered in the <a class="link" href="#dataaccess-chapt" title="Chapter&nbsp;7.&nbsp;Data Access and Change">Data Access and Change</a> chapter,
    which covers SQL in general. SQL expressions such as
    <code class="literal">COALESCE</code>, <code class="literal">NULLIF</code> and
    <code class="literal">CAST</code> are also discussed there.</p>
<p>The built-in functions fall into three groups:</p>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>SQL Standard Functions</p>
<p>A wide rang of functions defined by SQL/Foundation are
          supported. SQL/Foundation functions that have no parameter are
          called without empty parentheses. Functions with multiple parameters
          often use keywords instead of commas to separate the parameters.
          Many functions are overloaded. Among these, some have one or more
          optional parameters that can be omitted, while the return type of
          some functions is dependent upon the type of one of the parameters.
          The usage of SQL Standard Functions (where they can be used) is
          covered more extensively in the <a class="link" href="#dataaccess-chapt" title="Chapter&nbsp;7.&nbsp;Data Access and Change">Data Access and Change</a> chapter</p>
</li>
<li class="listitem">
<p>JDBC Open Group CLI Functions</p>
<p>These functions were defined as an extension to the CLI
          standard, which is the basis for ODBC and JDBC and supported by many
          database products. JDBC supports an escape mechanism to specify
          function calls in SQL statements in a manner that is independent of
          the function names supported by the target database engine. For
          example <code class="literal">SELECT {fn DAYOFMONTH (dateColumn)} FROM
          myTable</code> can be used in JDBC and is translated to Standard
          SQL as <code class="literal">SELECT EXTRACT (DAY_OF_MONTH FROM dateColumn) FROM
          myTable</code> if a database engine supports the Standard syntax.
          If a database engine does not support Standard SQL, then the
          translation will be different. HyperSQL supports all the function
          names specified in the JDBC specifications as native functions.
          Therefore, there is no need to use the <code class="literal">{fn FUNC_NAME ( ...
          ) }</code> escape with HyperSQL. If a JDBC function is supported
          by the SQL Standard in a different form, the SQL Standard form is
          the preferred form to use.</p>
</li>
<li class="listitem">
<p>HyperSQL Built-In Functions</p>
<p>Many additional built-in functions are available for some
          useful operations. Some of these functions return the current
          setting for the session and the database. The General Functions
          accept arguments of different types and return values based on
          comparison between the arguments.</p>
</li>
</ul>
</div>
<p>In the BNF specification used here, words in capital letters are
    actual tokens. Syntactic elements such as expressions are enclosed in
    angle brackets. The <code class="literal">&lt;left paren&gt;</code> and
    <code class="literal">&lt;right paren&gt;</code> tokens are represented with the
    actual symbol. Optional elements are enclosed with square brackets (
    <code class="literal">&lt;left bracket&gt;</code> and <code class="literal">&lt;right
    bracket&gt;</code> ). Multiple options for a required element are
    enclosed with braces (<code class="literal"> &lt;left brace&gt;</code> and
    <code class="literal">&lt;right brace&gt;</code> )<code class="literal">.</code> Alternative
    tokens are separated with the vertical bar ( <code class="literal">&lt;vertical
    bar&gt;</code> ). At the end of each function definition, the standard
    which specifies the function is noted in parentheses as JDBC or HyperSQL,
    or the SQL/Foundation part of the SQL Standard.</p>
</div>
<div class="section" title="String and Binary String Functions">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="bfc_string_binary_functions"></a>String and Binary String Functions</h2>
</div>
</div>
</div>
<p>In SQL, there are three kinds of string: character, binary and bit.
    The units are respectively characters, octets, and bits. Each kind of
    string can be in different data types. CHAR, VARCHAR and CLOB are the
    character data types. BINARY, VARBINARY and BLOB are the binary data
    types. BIT and BIT VARYING are the bit string types. In all string
    functions, the position of a unit of the string within the whole string is
    specified from 1 to the length of the whole string. In the BNF,
    <code class="literal">&lt;char value expr&gt; </code>indicates any valid SQL
    expression that evaluates to a character type. Likewise,
    <code class="literal">&lt;binary value expr&gt; </code>indicates a binary type
    and<code class="literal"> &lt;num value expr&gt; </code>indicates a numeric
    type.</p>
<a name="N13636" class="indexterm"></a>
<p>
<span class="bold"><strong>ASCII</strong></span>
</p>
<p>
<code class="literal">ASCII ( &lt;char value expr&gt; )</code>
</p>
<p>Returns an INTEGER equal to the ASCII code value of the first
    character of <code class="literal">&lt;char value expr&gt;</code>. (JDBC)</p>
<a name="N13647" class="indexterm"></a>
<p>
<span class="bold"><strong>BIT_LENGTH</strong></span>
</p>
<p>
<code class="literal">BIT_LENGTH ( &lt;string value expression&gt;
    )</code>
</p>
<p>BIT_LENGTH can be used with character, binary and bit strings. It
    return a BIGINT value that measures the bit length of the string.
    (Foundation)</p>
<p>See also CHARACTER_LENGTH and OCTET_LENGTH.</p>
<a name="N13657" class="indexterm"></a>
<p>
<span class="bold"><strong>CHAR</strong></span>
</p>
<p>
<code class="literal">CHAR ( &lt;UNICODE code&gt; ) </code>
</p>
<p>The argument is an INTEGER. Returns a character string containing a
    single character that has the specified<code class="literal"> &lt;UNICODE
    code&gt;</code>, which is an integer. ASCII codes are a subset of the
    allowed values for <code class="literal">&lt;UNICODE code&gt;</code>. (JDBC)</p>
<a name="N1366B" class="indexterm"></a><a name="N13670" class="indexterm"></a>
<p>
<span class="bold"><strong>CHARACTER_LENGTH</strong></span>
</p>
<p>
<code class="literal">{ CHAR_LENGTH | CHARACTER_LENGTH } ( &lt;char value
    expression&gt; [ USING { CHARACTERS | OCTETS } ] )</code>
</p>
<p>The CHAR_LENGTH or CHARACTER_LENGTH function can be used with
    character strings, while OCTET_LENGTH can be used with character or binary
    strings and BIT_LENGTH can be used with character, binary and bit
    strings.</p>
<p>All functions return a BIGINT value that measures the length of the
    string in the given unit. CHAR_LENGTH counts characters, OCTET_LENGTH
    counts octets and BIT_LENGTH counts bits in the string. For CHAR_LENGTH,
    if <code class="literal">[ USING OCTETS ] </code>is specified, the octet count is
    returned, which is twice the normal length. (Foundation)</p>
<a name="N13683" class="indexterm"></a>
<p>
<span class="bold"><strong>CONCAT</strong></span>
</p>
<p>
<code class="literal">CONCAT ( &lt;char value expr 1&gt;, &lt;char value expr
    2&gt; [, ...] )</code>
</p>
<p>
<code class="literal">CONCAT ( &lt;binary value expr 1&gt;, &lt;binary value expr
    2&gt; [, ...] )</code>
</p>
<p>The arguments are character strings or binary strings. Returns a
    string formed by concatenation of the arguments. Minimum number of
    arguments is 2. Equivalent to the SQL concatenation expression
    <code class="literal">&lt;value expr 1&gt; || &lt;value expr 2&gt; [ || ...] </code>
    .</p>
<p>Handling of null values in the CONCAT function depends on the
    database property <code class="literal">sql.concat_nulls</code> ( <code class="literal">SET
    DATABASE SQL SYNTAX CONCAT NULLS { TRUE || FALSE }</code> ). By
    default, any null value will cause the function to return null. If the
    property is set false, then NULL values are replaced with empty
    strings.</p>
<p>(JDBC)</p>
<a name="N136A1" class="indexterm"></a>
<p>
<span class="bold"><strong>CONCAT_WS</strong></span>
</p>
<p>
<code class="literal">CONCAT_WS ( &lt;char value separator&gt;, &lt;char value
    expr 1&gt;, &lt;char value expr 2&gt; [, ...] )</code>
</p>
<p>The arguments are character strings. Returns a string formed by
    concatenation of the arguments from the second argument, using the
    separator from the first argument. Minimum number of arguments is 3.
    Equivalent to the SQL concatenation expression <code class="literal">&lt;value expr
    1&gt; || &lt;separator&gt; || &lt;value expr 2&gt; [ || ...]</code> .
    The function ignores null values and returns an empty string if all values
    are null. It returns null only if the separator is null.</p>
<p>This function is similar to a MySQL function of the same
    name.</p>
<p>(HyperSQL)</p>
<a name="N136B6" class="indexterm"></a>
<p>
<span class="bold"><strong>DIFFERENCE</strong></span>
</p>
<p>
<code class="literal">DIFFERENCE ( &lt;char value expr 1&gt;, &lt;char value expr
    2&gt; )</code>
</p>
<p>The arguments are character strings. Converts the arguments into
    SOUNDEX codes, and returns an INTEGER between 0-4 which indicates how
    similar the two SOUNDEX value are. If the values are the same, it returns
    4, if the values have no similarity, it returns 0. In-between values are
    returned for partial similarity. (JDBC)</p>
<a name="N136C4" class="indexterm"></a>
<p>
<span class="bold"><strong>INSERT</strong></span>
</p>
<p>
<code class="literal">INSERT ( &lt;char value expr 1&gt;, &lt;offset&gt;,
    &lt;length&gt;, &lt;char value expr 2&gt; )</code>
</p>
<p>Returns a character string based on <code class="literal">&lt;char value expr
    1&gt;</code> in which <code class="literal">&lt;length&gt;</code> characters have
    been removed from the <code class="literal">&lt;offset&gt;</code> position and in
    their place, the whole <code class="literal">&lt;char value expr 2&gt;</code> is
    copied. Equivalent to SQL/Foundation <code class="literal">OVERLAY( &lt;char value
    expr1&gt; PLACING &lt; char value expr2&gt; FROM &lt;offset&gt; FOR
    &lt;length&gt; )</code> . (JDBC)</p>
<a name="N136E1" class="indexterm"></a>
<p>
<span class="bold"><strong>INSTR</strong></span>
</p>
<p>
<code class="literal">INSTR ( &lt;char value expr 1&gt;, &lt;char value expr
    2&gt; [ , &lt;offset&gt; ] ) </code>
</p>
<p>Returns as a BIGINT value the starting position of the first
    occurrence of <code class="literal">&lt;char value expr 2&gt;</code> within
    <code class="literal">&lt;char value expr 1&gt;</code>. If
    <code class="literal">&lt;offset</code>&gt; is specified, the search begins with the
    position indicated by <code class="literal">&lt;offset&gt;</code>. If the search is
    not successful, 0 is returned. Similar to the <code class="literal">LOCATE</code>
    function but the order of the arguments is reversed. (HyperSQL)</p>
<a name="N136FE" class="indexterm"></a>
<p>
<span class="bold"><strong>HEXTORAW</strong></span>
</p>
<p>
<code class="literal">HEXTORAW( &lt;char value expr&gt; )</code>
</p>
<p>Returns a BINARY string formed by translation of hexadecimal digits
    and letters in the &lt;<code class="literal">char value expr&gt;</code>. Each
    character of the <code class="literal">&lt;char value expr&gt;</code> must be a
    digit or a letter in the A | B | C | D | E | F set. Each byte of the
    retired binary string is formed by translating two hex digits into one
    byte. (HyperSQL)</p>
<a name="N13712" class="indexterm"></a>
<p>
<span class="bold"><strong>LCASE</strong></span>
</p>
<p>
<code class="literal">LCASE ( &lt;char value expr&gt; ) </code>
</p>
<p>Returns a character string that is the lower case version of the
    <code class="literal">&lt;char value expr&gt;</code>. Equivalent to SQL/Foundation
    <code class="literal">LOWER (&lt;char value expr&gt;)</code>. (JDBC)</p>
<a name="N13726" class="indexterm"></a>
<p>
<span class="bold"><strong>LEFT</strong></span>
</p>
<p>
<code class="literal">LEFT ( &lt;char value expr&gt;, &lt;count&gt; )
    </code>
</p>
<p>Returns a character string consisting of the first
    <code class="literal">&lt;count&gt;</code> characters of <code class="literal">&lt;char value
    expr&gt;</code>. Equivalent to SQL/Foundation<code class="literal">
    SUBSTRING(&lt;char value expr&gt; FROM 0 FOR &lt;count&gt;)</code>.
    (JDBC)</p>
<a name="N1373D" class="indexterm"></a>
<p>
<span class="bold"><strong>LENGTH</strong></span>
</p>
<p>
<code class="literal">LENGTH ( &lt;char value expr&gt; ) </code>
</p>
<p>Returns as a BIGINT value the number of characters in
    <code class="literal">&lt;char value expr&gt;</code>. Equivalent to SQL/Foundation
    <code class="literal">CHAR_LENGTH(&lt;char value expr&gt;)</code>. (JDBC)</p>
<a name="N13751" class="indexterm"></a>
<p>
<span class="bold"><strong>LOCATE</strong></span>
</p>
<p>
<code class="literal">LOCATE ( &lt;char value expr 1&gt;, &lt;char value expr
    2&gt; [ , &lt;offset&gt; ] ) </code>
</p>
<p>Returns as a BIGINT value the starting position of the first
    occurrence of <code class="literal">&lt;char value expr 1&gt;</code> within
    <code class="literal">&lt;char value expr 2&gt;</code>. If
    <code class="literal">&lt;offset</code>&gt; is specified, the search begins with the
    position indicated by <code class="literal">&lt;offset&gt;</code>. If the search is
    not successful, 0 is returned. Without the third argument,<code class="literal">
    LOCATE</code> is equivalent to the SQL Standard function
    <code class="literal">POSITION(&lt;char value expr 1&gt; IN &lt;char value expr
    2&gt;)</code>. (JDBC)</p>
<a name="N13771" class="indexterm"></a>
<p>
<span class="bold"><strong>LPAD</strong></span>
</p>
<p>
<code class="literal">LPAD ( &lt;char value expr 1&gt;, &lt;length&gt; [,
    &lt;char value expr 2&gt; ] ) </code>
</p>
<p>Returns a character string with the length of
    <code class="literal">&lt;length&gt;</code> characters. The string contains the
    characters of <code class="literal">&lt;char value expr 1&gt;</code> padded to the
    left with spaces. If <code class="literal">&lt;length&gt;</code> is smaller than the
    length of the string argument, the argument is truncated. If the optional
    <code class="literal">&lt;char value expr 2&gt;</code> is specified, this string is
    used for padding, instead of spaces. (HyperSQL)</p>
<a name="N1378B" class="indexterm"></a>
<p>
<span class="bold"><strong>LTRIM</strong></span>
</p>
<p>
<code class="literal">LTRIM ( &lt;char value expr&gt; ) </code>
</p>
<p>Returns a character string based on <code class="literal">&lt;char value
    expr&gt;</code> with the leading space characters removed. Equivalent
    to SQL/Foundation <code class="literal">TRIM( LEADING ' ' FROM &lt;char value expr&gt;
    )</code>. (JDBC)</p>
<a name="N1379F" class="indexterm"></a>
<p>
<span class="bold"><strong>OCTET_LENGTH</strong></span>
</p>
<p>
<code class="literal">OCTET_LENGTH ( &lt;string value expression&gt;
    )</code>
</p>
<p>The OCTET_LENGTH function can be used with character or binary
    strings.</p>
<p>Return a BIGINT value that measures the length of the string in
    octets<code class="literal">. When used with character strings</code>, the octet
    count is returned, which is twice the normal length. (Foundation)</p>
<a name="N137B2" class="indexterm"></a>
<p>
<span class="bold"><strong>OVERLAY</strong></span>
</p>
<p>
<code class="literal">OVERLAY ( &lt;char value expr 1&gt; PLACING &lt;char value
    expr 2&gt;</code>
</p>
<p>
<code class="literal">FROM &lt;start position&gt; [ FOR &lt;string length&gt; ] [
    USING CHARACTERS ] )</code>
</p>
<p>
<code class="literal">OVERLAY ( &lt;binary value expr 1&gt; PLACING &lt;binary
    value expr 2&gt;</code>
</p>
<p>
<code class="literal">FROM &lt;start position&gt; [ FOR &lt;string length&gt; ]
    )</code>
</p>
<p>The character version of OVERLAY returns a character string based on
    <code class="literal">&lt;char value expr 1&gt;</code> in which <code class="literal">&lt;string
    length&gt;</code> characters have been removed from the
    <code class="literal">&lt;start position&gt;</code> and in their place, the whole
    <code class="literal">&lt;char value expr 2&gt;</code> is copied.</p>
<p>The binary version of OVERLAY returns a binary string formed in the
    same manner as the character version. (Foundation)</p>
<a name="N137D7" class="indexterm"></a>
<p>
<span class="bold"><strong>POSITION</strong></span>
</p>
<p>
<code class="literal">POSITION ( &lt;char value expr 1&gt; IN &lt;char value expr
    2&gt; [ USING CHARACTERS ] )</code>
</p>
<p>
<code class="literal">POSITION ( &lt;binary value expr 1&gt; IN &lt;binary value
    expr 2&gt; )</code>
</p>
<p>The character and binary versions of POSITION search the string
    value of the second argument for the first occurrence of the first
    argument string. If the search is successful, the position in the string
    is returned as a BIGINT. Otherwise zero is returned. (Foundation)</p>
<a name="N137E8" class="indexterm"></a>
<p>
<span class="bold"><strong>RAWTOHEX</strong></span>
</p>
<p>
<code class="literal">RAWTOHEX( &lt;binary value expr&gt; )</code>
</p>
<p>Returns a character string composed of hexadecimal digits
    representing the bytes in the <code class="literal">&lt;binary value
    expr&gt;</code>. Each byte of the <code class="literal">&lt;binary value
    expr&gt;</code> is translated into two hex digits. (HyperSQL)</p>
<a name="N137FC" class="indexterm"></a>
<p>
<span class="bold"><strong>REGEXP_MATCHES</strong></span>
</p>
<p>
<code class="literal">REGEXP_MATCHES ( &lt;char value expr&gt;, &lt;regular
    expression&gt; ) </code>
</p>
<p>Returns true if the <code class="literal">&lt;char value expr&gt;</code>
    matches the <code class="literal">&lt;regular expression&gt;</code> as a whole. The
    <code class="literal">&lt;regular expression&gt;</code> is defined according to Java
    language regular expression rules. (HyperSQL)</p>
<a name="N13813" class="indexterm"></a>
<p>
<span class="bold"><strong>REGEXP_SUBSTRING</strong></span>
</p>
<p>
<code class="literal">REGEXP_SUBSTRING ( &lt;char value expr&gt;, &lt;regular
    expression&gt; ) </code>
</p>
<p>Returns the first region in the <code class="literal">&lt;char value
    expr&gt;</code> that matches the <code class="literal">&lt;regular
    expression&gt;</code>. The <code class="literal">&lt;regular
    expression&gt;</code> is defined according to Java language regular
    expression rules. (HyperSQL)</p>
<a name="N1382A" class="indexterm"></a>
<p>
<span class="bold"><strong>REGEXP_SUBSTRING_ARRAY</strong></span>
</p>
<p>
<code class="literal">REGEXP_SUBSTRING_ARRAY ( &lt;char value expr&gt;,
    &lt;regular expression&gt; ) </code>
</p>
<p>Returns all the regions in the the <code class="literal">&lt;char value
    expr&gt;</code> that match the <code class="literal">&lt;regular
    expression&gt;</code>. The <code class="literal">&lt;regular
    expression&gt;</code> is defined according to Java language regular
    expression rules. Returns an array containing the matching regions
    (HyperSQL)</p>
<a name="N13841" class="indexterm"></a>
<p>
<span class="bold"><strong>REPEAT</strong></span>
</p>
<p>
<code class="literal">REPEAT ( &lt;char value expr&gt;, &lt;count&gt; )
    </code>
</p>
<p>Returns a character string based on<code class="literal"> &lt;char value
    expr&gt;</code>, repeated <code class="literal">&lt;count&gt;</code> times.
    (JDBC)</p>
<a name="N13855" class="indexterm"></a>
<p>
<span class="bold"><strong>REPLACE</strong></span>
</p>
<p>
<code class="literal">REPLACE ( &lt;char value expr 1&gt;, &lt;char value expr
    2&gt; [, &lt;char value expr 3&gt; ] )</code>
</p>
<p>Returns a character string based on <code class="literal">&lt;char value expr
    1&gt;</code> where each occurrence of <code class="literal">&lt;char value expr
    2&gt;</code> has been replaced with a copy of <code class="literal">&lt;char value
    expr 3&gt;</code>. If the function is called with just two arguments,
    the &lt;char value expr 3&gt; defaults to the empty string and calling the
    function simply removes the occurrences of <code class="literal">&lt;char value expr
    2&gt;</code> from the first string.(JDBC)</p>
<a name="N1386F" class="indexterm"></a>
<p>
<span class="bold"><strong>REVERSE</strong></span>
</p>
<p>
<code class="literal">REVERSE ( &lt;char value expr&gt; )</code>
</p>
<p>Returns a character string based on <code class="literal">&lt;char value
    expr&gt;</code> with characters in the reverse order. (HyperSQL)</p>
<a name="N13880" class="indexterm"></a>
<p>
<span class="bold"><strong>RIGHT</strong></span>
</p>
<p>
<code class="literal">RIGHT ( &lt;char value expr&gt;, &lt;count&gt; )
    </code>
</p>
<p>Returns a character string consisting of the last
    <code class="literal">&lt;count&gt;</code> characters of <code class="literal">&lt;char value
    expr&gt;</code>. (JDBC)</p>
<a name="N13894" class="indexterm"></a>
<p>
<span class="bold"><strong>RPAD</strong></span>
</p>
<p>
<code class="literal">RPAD ( &lt;char value expr 1&gt;, &lt;length&gt; [,
    &lt;char value expr 2&gt; ] ) </code>
</p>
<p>Returns a character string with the length of
    <code class="literal">&lt;length&gt;</code> characters. The string begins with the
    characters of <code class="literal">&lt;char value expr 1&gt;</code> padded to the
    right with spaces. If <code class="literal">&lt;length&gt;</code> is smaller than
    the length of the string argument, the argument is truncated. If the
    optional <code class="literal">&lt;char value expr 2&gt;</code> is specified, this
    string is used for padding, instead of spaces. (HyperSQL)</p>
<a name="N138AE" class="indexterm"></a>
<p>
<span class="bold"><strong>RTRIM</strong></span>
</p>
<p>
<code class="literal">RTRIM ( &lt;char value expr&gt; ) </code>
</p>
<p>Returns a character string based on <code class="literal">&lt;char value
    expr&gt;</code> with the trailing space characters removed. Equivalent
    to SQL/Foundation <code class="literal">TRIM(TRAILING ' ' FROM &lt;character
    string&gt;)</code>. (JDBC)</p>
<a name="N138C2" class="indexterm"></a>
<p>
<span class="bold"><strong>SOUNDEX</strong></span>
</p>
<p>
<code class="literal">SOUNDEX ( &lt;char value expr&gt; ) </code>
</p>
<p>Returns a four character code representing the sound of
    <code class="literal">&lt;char value expr&gt;</code>. The US census algorithm is
    used. For example the soundex value for Washington is W252. (JDBC)</p>
<a name="N138D3" class="indexterm"></a>
<p>
<span class="bold"><strong>SPACE</strong></span>
</p>
<p>
<code class="literal">SPACE ( &lt;count&gt; ) </code>
</p>
<p>Returns a character string consisting of <code class="literal">&lt;count&gt;
    </code>spaces. (JDBC)</p>
<a name="N138E4" class="indexterm"></a>
<p>
<span class="bold"><strong>SUBSTR</strong></span>
</p>
<p>
<code class="literal">{ SUBSTR | SUBSTRING } ( &lt;char value expr&gt;,
    &lt;offset&gt;, &lt;length&gt; )</code>
</p>
<p>The JDBC version of SQL/Foundation <code class="literal">SUBSTRING</code>
    returns a character string that consists of
    <code class="literal">&lt;length&gt;</code> characters from <code class="literal">&lt;char value
    expr&gt; </code>starting at the <code class="literal">&lt;offset&gt;</code>
    position. (JDBC)</p>
<a name="N138FE" class="indexterm"></a>
<p>
<span class="bold"><strong>SUBSTRING</strong></span>
</p>
<p>
<code class="literal">SUBSTRING ( &lt;char value expr&gt; FROM &lt;start
    position&gt; [ FOR &lt;string length&gt; ] [ USING CHARACTERS ]
    )</code>
</p>
<p>
<code class="literal">SUBSTRING ( &lt;binary value expr&gt; FROM &lt;start
    position&gt; [ FOR &lt;string length&gt; ] )</code>
</p>
<p>The character version of SUBSTRING returns a character string that
    consists of the characters of the <code class="literal">&lt;char value expr&gt;
    </code>from <code class="literal">&lt;start position&gt;</code>. If the
    optional<code class="literal"> &lt;string length&gt;</code> is specified, only
    <code class="literal">&lt;string length&gt; </code>characters are returned.</p>
<p>The binary version of SUBSTRING returns a binary string in the same
    manner. (Foundation)</p>
<a name="N1391D" class="indexterm"></a>
<p>
<span class="bold"><strong>TRIM</strong></span>
</p>
<p>
<code class="literal">TRIM ([ [ LEADING | TRAILING | BOTH ] [ &lt;trim
    character&gt; ] FROM ] &lt;char value expr&gt; )</code>
</p>
<p>
<code class="literal">TRIM ([ [ LEADING | TRAILING | BOTH ] [ &lt;trim octet&gt;
    ] FROM ] &lt;binary value expr&gt; )</code>
</p>
<p>The character version of TRIM returns a character string based on
    <code class="literal">&lt;char value expr&gt;</code>. Consecutive instances of
    <code class="literal">&lt;trim character&gt; </code>are removed from the beginning,
    the end or both ends of the<code class="literal">&lt;char value expr&gt;
    </code>depending on the value of the optional first qualifier
    <code class="literal">[ LEADING | TRAILING | BOTH ]</code>. If no qualifier is
    specified, <code class="literal">BOTH </code>is used as default. If <code class="literal">[
    &lt;trim character&gt; ]</code> is not specified, the space character
    is used as default.</p>
<p>The binary version of TRIM returns a binary string based on
    <code class="literal">&lt;binary value expr&gt;</code>. Consecutive instances of
    <code class="literal">&lt;trim octet&gt; </code>are removed in the same manner as in
    the character version. If<code class="literal"> [ &lt;trim octet&gt; ]</code> is not
    specified, the 0 octet is used as default. (Foundation)</p>
<a name="N1394B" class="indexterm"></a>
<p>
<span class="bold"><strong>TRANSLATE</strong></span>
</p>
<p>
<code class="literal">TRANSLATE( &lt;char value expr1&gt;, &lt;char value
    expr2&gt;, &lt;char value expr3&gt; )</code>
</p>
<p>Returns a character string based on <code class="literal">&lt;char value
    expr1&gt;</code> source. Each character of the source is checked
    against the characters in <code class="literal">&lt;char value expr2&gt;</code>. If
    the character is not found, it is not modified. If the character is found,
    then the character in the same position in <code class="literal">&lt;char value
    expr3&gt;</code> is used. If <code class="literal">&lt;char value
    expr2&gt;</code> is longer than <code class="literal">&lt;char value
    expr3&gt;</code>, then those characters at the end that have no
    counterpart in <code class="literal">&lt;char value expr3&gt;</code> are dropped
    from the result. (HyperSQL)</p>
<pre class="programlisting"> -- in this example any accented character in acolumn is replaced with one without an accent
 TRANSLATE( acolumn, '&Aacute;&Ccedil;&Eacute;&Iacute;&Oacute;&Uacute;&Agrave;&Egrave;&Igrave;&Ograve;&Ugrave;&Acirc;&Ecirc;&Icirc;&Ocirc;&Ucirc;&Atilde;&Otilde;&Euml;&Uuml;&aacute;&ccedil;&eacute;&iacute;&oacute;&uacute;&agrave;&egrave;&igrave;&ograve;&ugrave;&acirc;&ecirc;&icirc;&ocirc;&ucirc;&atilde;&otilde;&euml;&uuml;', 'ACEIOUAEIOUAEIOUAOEUaceiouaeiouaeiouaoeu');
</pre>
<a name="N1396D" class="indexterm"></a>
<p>
<span class="bold"><strong>UCASE</strong></span>
</p>
<p>
<code class="literal">UCASE ( &lt;char value expr&gt; ) </code>
</p>
<p>Returns a character string that is the upper case version of the
    <code class="literal">&lt;char value expr&gt;</code>. Equivalent to SQL/Foundation
    <code class="literal">UPPER( &lt;char value expr&gt; )</code> . (JDBC)</p>
<a name="N13981" class="indexterm"></a>
<p>
<span class="bold"><strong>UPPER</strong></span>
</p>
<p>
<code class="literal">UPPER ( &lt;char value expr&gt; ) </code>
</p>
<p>Returns a character string that is the upper case version of the
    <code class="literal">&lt;char value expr&gt;</code> . (Foundation)</p>
</div>
<div class="section" title="Numeric Functions">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="bfc_numeric_functions"></a>Numeric Functions</h2>
</div>
</div>
</div>
<a name="N13996" class="indexterm"></a>
<p>
<span class="bold"><strong>ABS</strong></span>
</p>
<p>
<code class="literal">ABS ( &lt;num value expr&gt; | &lt;interval value expr&gt;
    ) </code>
</p>
<p>Returns the absolute value of the argument as a value of the same
    type. (JDBC and Foundation)</p>
<a name="N139A4" class="indexterm"></a>
<p>
<span class="bold"><strong>ACOS</strong></span>
</p>
<p>
<code class="literal">ACOS ( &lt;num value expr&gt; ) </code>
</p>
<p>Returns the arc-cosine of the argument in radians as a value of
    DOUBLE type. (JDBC)</p>
<a name="N139B2" class="indexterm"></a>
<p>
<span class="bold"><strong>ASIN</strong></span>
</p>
<p>
<code class="literal">ASIN ( &lt;num value expr&gt; ) </code>
</p>
<p>Returns the arc-sine of the argument in radians as a value of DOUBLE
    type. (JDBC)</p>
<a name="N139C0" class="indexterm"></a>
<p>
<span class="bold"><strong>ATAN</strong></span>
</p>
<p>
<code class="literal">ATAN ( &lt;num value expr&gt; ) </code>
</p>
<p>Returns the arc-tangent of the argument in radians as a value of
    DOUBLE type. (JDBC)</p>
<a name="N139CE" class="indexterm"></a>
<p>
<span class="bold"><strong>ATAN2</strong></span>
</p>
<p>
<code class="literal">ATAN2 ( &lt;num value expr 1&gt;, &lt;num value expr 2&gt;
    ) </code>
</p>
<p>The <code class="literal">&lt;num value expr 1&gt;</code> and <code class="literal">&lt;num
    value expr 2&gt;</code> express the <code class="varname">x</code> and
    <code class="varname">y</code> coordinates of a point. Returns the angle, in
    radians, representing the angle coordinate of the point in polar
    coordinates, as a value of DOUBLE type. (JDBC)</p>
<a name="N139E8" class="indexterm"></a>
<p>
<span class="bold"><strong>CEILING</strong></span>
</p>
<p>
<code class="literal">{ CEIL | CEILING } ( &lt;num value expr&gt; )
    </code>
</p>
<p>Returns the smallest integer greater than or equal to the argument.
    If the argument is exact numeric then the result is exact numeric with a
    scale of 0. If the argument is approximate numeric, then the result is of
    DOUBLE type. (JDBC and Foundation)</p>
<a name="N139F6" class="indexterm"></a>
<p>
<span class="bold"><strong>BITAND</strong></span>
</p>
<p>
<code class="literal">BITAND ( &lt;num value expr 1&gt;, &lt;num value expr 2&gt;
    )</code>
</p>
<p>
<code class="literal">BITAND ( &lt;bit value expr 1&gt;, &lt;bit value expr 2&gt;
    )</code>
</p>
<a name="N13A05" class="indexterm"></a>
<p>
<span class="bold"><strong>BITANDNOT</strong></span>
</p>
<p>
<code class="literal">BITANDNOT ( &lt;num value expr 1&gt;, &lt;num value expr
    2&gt; )</code>
</p>
<p>
<code class="literal">BITANDNOT ( &lt;bit value expr 1&gt;, &lt;bit value expr
    2&gt; )</code>
</p>
<a name="N13A14" class="indexterm"></a>
<p>
<span class="bold"><strong>BITNOT</strong></span>
</p>
<p>
<code class="literal">BITNOT ( &lt;num value expr 1&gt; )</code>
</p>
<p>
<code class="literal">BITNOT ( &lt;bit value expr 1&gt; )</code>
</p>
<a name="N13A23" class="indexterm"></a>
<p>
<span class="bold"><strong>BITOR</strong></span>
</p>
<p>
<code class="literal">BITOR ( &lt;num value expr 1&gt;, &lt;num value expr 2&gt;
    )</code>
</p>
<p>
<code class="literal">BITOR ( &lt;bit value expr 1&gt;, &lt;bit value expr 2&gt;
    )</code>
</p>
<a name="N13A32" class="indexterm"></a>
<p>
<span class="bold"><strong>BITXOR</strong></span>
</p>
<p>
<code class="literal">BITXOR ( &lt;num value expr 1&gt;, &lt;num value expr 2&gt;
    )</code>
</p>
<p>
<code class="literal">BITXOR ( &lt;bit value expr 1&gt;, &lt;bit value expr 2&gt;
    )</code>
</p>
<p>These functions bit operations on two values, or in the case of
    BITNOT on a single values. The values are either integer values, or bit
    strings. The result is an integer value of the same type as the arguments,
    or a bit string of the same length as the argument. Each bit of the result
    is formed by performing the operation on corresponding bits of the
    arguments. The names of the function indicate NOT, OR, AND, XOR
    operations. The BITANDNOT performs NOT on the second argument, then
    performs AND on result and the first argument. (HyperSQL)</p>
<a name="N13A43" class="indexterm"></a>
<p>
<span class="bold"><strong>COS</strong></span>
</p>
<p>
<code class="literal">COS ( &lt;num value expr&gt; ) </code>
</p>
<p>Returns the cosine of the argument (an angle expressed in radians)
    as a value of DOUBLE type. (JDBC)</p>
<a name="N13A51" class="indexterm"></a>
<p>
<span class="bold"><strong>COT</strong></span>
</p>
<p>
<code class="literal">COT ( &lt;num value expr&gt; ) </code>
</p>
<p>Returns the cotangent of the argument as a value of DOUBLE type. The
    <code class="literal">&lt;num value expr&gt;</code> represents an angle expressed in
    radians. (JDBC)</p>
<a name="N13A62" class="indexterm"></a>
<p>
<span class="bold"><strong>DEGREES</strong></span>
</p>
<p>
<code class="literal">DEGREES ( &lt;num value expr&gt; ) </code>
</p>
<p>Converts the argument (an angle expressed in<code class="literal">
    radians</code>) into degrees and returns the value in the DOUBLE type.
    (JDBC)</p>
<a name="N13A73" class="indexterm"></a>
<p>
<span class="bold"><strong>EXP</strong></span>
</p>
<p>
<code class="literal">EXP ( &lt;num value expr&gt; ) </code>
</p>
<p>Returns the exponential value of the argument as a value of DOUBLE
    type. (JDBC and Foundation)</p>
<a name="N13A81" class="indexterm"></a>
<p>
<span class="bold"><strong>FLOOR</strong></span>
</p>
<p>
<code class="literal">FLOOR ( &lt;num value expr&gt; ) </code>
</p>
<p>Returns the largest integer that is less than or equal to the
    argument. If the argument is exact numeric then the result is exact
    numeric with a scale of 0. If the argument is approximate numeric, then
    the result is of DOUBLE type. (JDBC and Foundation)</p>
<a name="N13A8F" class="indexterm"></a>
<p>
<span class="bold"><strong>LN</strong></span>
</p>
<p>
<code class="literal">LN ( &lt;num value expr&gt; ) </code>
</p>
<p>Returns the natural logarithm of the argument, as a value of DOUBLE
    type. (Foundation)</p>
<a name="N13A9D" class="indexterm"></a>
<p>
<span class="bold"><strong>LOG</strong></span>
</p>
<p>
<code class="literal">LOG ( &lt;num value expr&gt; ) </code>
</p>
<p>Returns the natural logarithm of the argument, as a value of DOUBLE
    type. (JDBC)</p>
<a name="N13AAB" class="indexterm"></a>
<p>
<span class="bold"><strong>LOG10</strong></span>
</p>
<p>
<code class="literal">LOG10 ( &lt;num value expr&gt; ) </code>
</p>
<p>Returns the base 10 logarithm of the argument as a value of DOUBLE
    type. (JDBC)</p>
<p>
<code class="literal">MOD ( &lt;num value expr 1&gt;, &lt;num value expr 2&gt; )
    </code>
</p>
<a name="N13ABC" class="indexterm"></a>
<p>
<span class="bold"><strong>MOD</strong></span>
</p>
<p>Returns the remainder (modulus) of <code class="literal">&lt;num value expr
    1&gt;</code> divided by <code class="literal">&lt;num value expr 2&gt;.</code>
    The data type of the returned value is the same as the second argument.
    (JDBC and Foundation)</p>
<a name="N13ACD" class="indexterm"></a>
<p>
<span class="bold"><strong>PI</strong></span>
</p>
<p>
<code class="literal">PI () </code>
</p>
<p>Returns the constant pi as a value of DOUBLE type. (JDBC)</p>
<a name="N13ADB" class="indexterm"></a>
<p>
<span class="bold"><strong>POWER</strong></span>
</p>
<p>
<code class="literal">POWER ( &lt;num value expr 1&gt;, &lt;num value expr 2&gt;
    ) </code>
</p>
<p>Returns the value of <code class="literal">&lt;num value expr 1&gt;</code>
    raised to the power of <code class="literal">&lt;int value expr 2&gt;</code> as a
    value of DOUBLE type. (JDBC and Foundation)</p>
<a name="N13AEF" class="indexterm"></a>
<p>
<span class="bold"><strong>RADIANS</strong></span>
</p>
<p>
<code class="literal">RADIANS ( &lt;num value expr&gt; ) </code>
</p>
<p>Converts the argument (an angle expressed in<code class="literal">
    degrees</code>) into radians and returns the value in the DOUBLE type.
    (JDBC)</p>
<a name="N13B00" class="indexterm"></a>
<p>
<span class="bold"><strong>RAND</strong></span>
</p>
<p>
<code class="literal">RAND ( [ &lt;int value expr&gt; ] ) </code>
</p>
<p>Returns a random value in the DOUBLE type. The optional <code class="literal">[
    &lt;int value expr&gt; ]</code> is used as seed value. In HyperSQL each
    session has a separate random number generator. The first call that uses a
    seed parameter sets the seed for subsequent calls that do not include a
    parameter. (JDBC)</p>
<a name="N13B11" class="indexterm"></a>
<p>
<span class="bold"><strong>ROUND</strong></span>
</p>
<p>
<code class="literal">ROUND ( &lt;num value expr&gt;, &lt;int value expr&gt; )
    </code>
</p>
<p>The <code class="literal">&lt;num value expr&gt; </code>is of the DOUBLE type
    or DECIMAL type. The function returns a DOUBLE or DECIMAL value which is
    the value of the argument rounded to <code class="literal">&lt;int value
    expr&gt;</code> places right of the decimal point. If <code class="literal">&lt;int
    value expr&gt;</code> is negative, the first argument is rounded to
    <code class="literal">&lt;int value expr&gt;</code> places to the left of the
    decimal point.</p>
<p>This function rounds values ending with .5 or larger away from zero
    for DECIMAL arguments and results. When the value ends with .5 or larger
    and the argument and result are DOUBLE, It rounds the value towards the
    closest even value.</p>
<p>The datetime version is discussed in the next section. (JDBC)</p>
<a name="N13B2F" class="indexterm"></a>
<p>
<span class="bold"><strong>SIGN</strong></span>
</p>
<p>
<code class="literal">SIGN ( &lt;num value expr&gt; ) </code>
</p>
<p>Returns an INTEGER, indicating the sign of the argument. If the
    argument is negative then -1 is returned. If it is equal to zero then 0 is
    returned. If the argument is positive then 1 is returned. (JDBC)</p>
<a name="N13B3D" class="indexterm"></a>
<p>
<span class="bold"><strong>SIN</strong></span>
</p>
<p>
<code class="literal">SIN ( &lt;num value expr&gt; ) </code>
</p>
<p>Returns the sine of the argument (an angle expressed in radians) as
    a value of DOUBLE type. (JDBC)</p>
<a name="N13B4B" class="indexterm"></a>
<p>
<span class="bold"><strong>SQRT</strong></span>
</p>
<p>
<code class="literal">SQRT ( &lt;num value expr&gt; ) </code>
</p>
<p>Returns the square root of the argument as a value of DOUBLE type.
    (JDBC and Foundation)</p>
<a name="N13B59" class="indexterm"></a>
<p>
<span class="bold"><strong>TAN</strong></span>
</p>
<p>
<code class="literal">TAN ( &lt;num value expr&gt; ) </code>
</p>
<p>Returns the tangent of the argument (an angle expressed in radians)
    as a value of DOUBLE type. (JDBC)</p>
<a name="N13B67" class="indexterm"></a>
<p>
<span class="bold"><strong>TO_NUMBER</strong></span>
</p>
<p>
<code class="literal">TO_NUMBER ( &lt;char value expr&gt; ) </code>
</p>
<p>Performs a cast from character to DECIMAL number. The character
    string must consist of digits and can have a decimal point. Use the SQL
    Standard CAST expression instead of this non-standard function.
    (HyperSQL)</p>
<a name="N13B75" class="indexterm"></a>
<p>
<span class="bold"><strong>TRUNC</strong></span>
</p>
<p>
<code class="literal">TRUNC ( &lt;num value expr&gt; [, &lt;int value expr&gt;] )
    </code>
</p>
<p>This is a similar to the <code class="literal">TRUNCATE</code> function when
    the first argument is numeric. If the second argument is omitted, zero is
    used in its place.</p>
<p>The datetime version is discussed in the next section.
    (HyperSQL)</p>
<a name="N13B88" class="indexterm"></a>
<p>
<span class="bold"><strong>TRUNCATE</strong></span>
</p>
<p>
<code class="literal">TRUNCATE ( &lt;num value expr&gt; [, &lt;int value
    expr&gt;] ) </code>
</p>
<p>Returns a value in the same type as <code class="literal">&lt;num value
    expr&gt;</code> but may reduce the scale of DECIMAL and NUMERIC values.
    The value is rounded by replacing digits with zeros from <code class="literal">&lt;int
    value expr&gt;</code> places right of the decimal point to the end. If
    <code class="literal">&lt;int value expr&gt;</code> is negative, <code class="literal">ABS(
    &lt;int value expr&gt; )</code> digits to left of the decimal point and
    all digits to the right of the decimal points are replaced with zeros.
    Results of calling TRUNCATE with 12345.6789 with (-2, 0, 2, 4) are (12300,
    12345, 12345.67, 12345.6789). The function does not change the number if
    the second argument is larger than or equal to the scale of the first
    argument.</p>
<p>If the second argument is not a constant (when it is a parameter or
    column reference) then the type of the return value is always the same as
    the type of the first argument. In this case, the discarded digits are
    replaced with zeros. (JDBC)</p>
<a name="N13BA4" class="indexterm"></a>
<p>
<span class="bold"><strong>WIDTH_BUCKET</strong></span>
</p>
<p>
<code class="literal">WIDTH_BUCKET ( &lt;value expr 1&gt; , &lt;value expr 2&gt;,
    &lt;value expr 3&gt;, &lt;int value expr&gt; ) </code>
</p>
<p>Returns an integer value between 0 and <code class="literal">&lt;int value
    expr&gt; + 1</code>. The initial three parameters are of the same
    numeric or datetime type. The range, ( <code class="literal">&lt;value expr 2&gt; ,
    &lt;value expr 3&gt;</code> ) is divided into <code class="literal">&lt;int value
    expr&gt;</code> equal sections (buckets). The returned integer value
    indicates the index of the bucket where <code class="literal">&lt;value expr
    1&gt;</code> can be placed. If the <code class="literal">&lt;value expr
    1&gt;</code> falls before or after the range, the return value is 0 or
    <code class="literal">&lt;value expr 1&gt; + 1</code> respectively.</p>
<p>This function can be used with numeric or datetime values. Invalid
    arguments, including <code class="literal">&lt;int value expr&gt;</code> smaller
    than 1, or equal values for <code class="literal">&lt;value expr 2&gt;</code> and
    <code class="literal">&lt;value expr 3&gt;</code> will cause an exception.
    (Foundation)</p>
<p>An example is given below:</p>
<pre class="programlisting"> WIDTH_BUCKET( 5, 10, 110, 10)
 0

 WIDTH_BUCKET( 23, 10, 110, 10)
 2

 WIDTH_BUCKET( 100, 10, 110, 10)
 10

 WIDTH_BUCKET( 200, 10, 110, 10)
 11
</pre>
</div>
<div class="section" title="Date Time and Interval Functions">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="bfc_datetime_functions"></a>Date Time and Interval Functions</h2>
</div>
</div>
</div>
<p>Functions to report the time zone.</p>
<div class="section" title="Functions to Report the Time Zone.">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="bfc_timezone_functions"></a>Functions to Report the Time Zone.</h3>
</div>
</div>
</div>
<a name="N13BDD" class="indexterm"></a>
<p>
<span class="bold"><strong>TIMEZONE</strong></span>
</p>
<p>
<code class="literal">TIMEZONE()</code>
</p>
<p>Returns the current time zone for the session. Returns an INTERVAL
      HOUR TO MINUTE value. (HyperSQL)</p>
<a name="N13BEB" class="indexterm"></a>
<p>
<span class="bold"><strong>SESSION_TIMEZONE</strong></span>
</p>
<p>
<code class="literal">SESSION_TIMEZONE()</code>
</p>
<p>Returns the default time zone for the current session. Returns an
      INTERVAL HOUR TO MINUTE value. (HyperSQL)</p>
<a name="N13BF9" class="indexterm"></a>
<p>
<span class="bold"><strong>SESSIONTIMEZONE</strong></span>
</p>
<p>
<code class="literal">SESSIONTIMEZONE()</code>
</p>
<p>Same as SESSION_TIMEZONE. (HyperSQL)</p>
<a name="N13C07" class="indexterm"></a>
<p>
<span class="bold"><strong>DATABASE_TIMEZONE</strong></span>
</p>
<p>
<code class="literal">DATABASE_TIMEZONE()</code>
</p>
<p>Returns the time zone for the database engine. This is based on
      where the database server process is located. Returns an INTERVAL HOUR
      TO MINUTE value. (HyperSQL)</p>
<p>
<span class="bold"><strong>DBTIMEZONE</strong></span>
</p>
<p>
<code class="literal">DBTIMEZONE()</code>
</p>
<p>Same as DATABASE_TIMEZONE. (HyperSQL)</p>
</div>
<div class="section" title="Functions to Report the Current Datetime">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="bfc_current_datetime"></a>Functions to Report the Current Datetime</h3>
</div>
</div>
</div>
<a name="N13C22" class="indexterm"></a>
<p>
<span class="bold"><strong>CURRENT_DATE</strong></span>
</p>
<p>
<code class="literal">CURRENT_DATE</code>
</p>
<a name="N13C2E" class="indexterm"></a>
<p>
<span class="bold"><strong>CURRENT_TIME</strong></span>
</p>
<p>
<code class="literal">CURRENT_TIME [ ( &lt;time precision&gt; )
      ]</code>
</p>
<a name="N13C3A" class="indexterm"></a>
<p>
<span class="bold"><strong>LOCALTIME</strong></span>
</p>
<p>
<code class="literal">LOCALTIME [ ( &lt;time precision&gt; ) ]</code>
</p>
<a name="N13C46" class="indexterm"></a>
<p>
<span class="bold"><strong>CURRENT_TIMESTAMP</strong></span>
</p>
<p>
<code class="literal">CURRENT_TIMESTAMP [ ( &lt;timestamp precision&gt; )
      ]</code>
</p>
<a name="N13C52" class="indexterm"></a>
<p>
<span class="bold"><strong>LOCALTIMESTAMP</strong></span>
</p>
<p>
<code class="literal">LOCALTIMESTAMP [ ( &lt;timestamp precision&gt; )
      ]</code>
</p>
<p>These datetime functions return the datetime value representing
      the moment the function is called. CURRENT_DATE returns a value of DATE
      type. CURRENT_TIME returns a value of TIME WITH TIME ZONE type.
      LOCALTIME returns a value of TIME type. CURRENT_TIMESTAMP returns a
      value of TIMESTAMP WITH TIME ZONE type. LOCALTIMESTAMP returns a value
      of TIMESTAMP type. If the optional <code class="literal">[ ( &lt;time precision&gt; )
      ]</code> or<code class="literal"> [ ( &lt;timestamp precision&gt; ) ]</code> is
      used, then the returned value has the specified fraction of the second
      precision. (Foundation)</p>
<a name="N13C66" class="indexterm"></a>
<p>
<span class="bold"><strong>NOW</strong></span>
</p>
<p>
<code class="literal">NOW ()</code>
</p>
<p>This function is equivalent to <code class="literal">LOCALTIMESTAMP</code>.
      It can be used as a no-arg function as the parens are optional.
      (HyperSQL)</p>
<a name="N13C77" class="indexterm"></a>
<p>
<span class="bold"><strong>CURDATE</strong></span>
</p>
<p>
<code class="literal">CURDATE ()</code>
</p>
<p>This function is equivalent to<code class="literal"> CURRENT_DATE</code>.
      (JDBC)</p>
<a name="N13C88" class="indexterm"></a>
<p>
<span class="bold"><strong>CURTIME</strong></span>
</p>
<p>
<code class="literal">CURTIME ()</code>
</p>
<p>This function is equivalent to<code class="literal"> LOCALTIME</code>.
      (JDBC)</p>
<a name="N13C99" class="indexterm"></a>
<p>
<span class="bold"><strong>SYSDATE</strong></span>
</p>
<p>
<code class="literal">SYSDATE</code>
</p>
<p>This function is equivalent to <code class="literal">LOCALTIMESTAMP.
      </code>(HyperSQL)</p>
<a name="N13CAA" class="indexterm"></a>
<p>
<span class="bold"><strong>SYSTIMESTAMP</strong></span>
</p>
<p>
<code class="literal">SYSTIMESTAMP</code>
</p>
<p>This no-arg function is equivalent to
      <code class="literal">CURRENT_TIMESTAMP</code> and is enabled in ORA syntax mode
      only. (HyperSQL)</p>
<a name="N13CBB" class="indexterm"></a>
<p>
<span class="bold"><strong>TODAY</strong></span>
</p>
<p>
<code class="literal">TODAY</code>
</p>
<p>This no-arg function is equivalent to<code class="literal"> CURRENT_DATE.
      </code>(HyperSQL)</p>
</div>
<div class="section" title="Functions to Extract an Element of a Datetime">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="bfc_extract_datetime"></a>Functions to Extract an Element of a Datetime</h3>
</div>
</div>
</div>
<a name="N13CD0" class="indexterm"></a>
<p>
<span class="bold"><strong>DAYNAME</strong></span>
</p>
<p>
<code class="literal">DAYNAME ( &lt;datetime value expr&gt; )</code>
</p>
<p>This function is equivalent to<code class="literal"> EXTRACT ( DAY_NAME FROM
      ... ) </code>Returns a string in the range of Sunday - Saturday.
      (JDBC)</p>
<a name="N13CE1" class="indexterm"></a>
<p>
<span class="bold"><strong>DAYOFMONTH</strong></span>
</p>
<p>
<code class="literal">DAYOFMONTH ( &lt;datetime value expr&gt;
      )</code>
</p>
<p>This function is equivalent to<code class="literal"> EXTRACT ( DAY_OF_MONTH
      FROM ... ) </code>Returns an integer value in the range of 1-31.
      (JDBC)</p>
<a name="N13CF2" class="indexterm"></a>
<p>
<span class="bold"><strong>DAYOFWEEK</strong></span>
</p>
<p>
<code class="literal">DAYOFWEEK ( &lt;datetime value expr&gt;
      )</code>
</p>
<p>This function is equivalent to <code class="literal">EXTRACT ( DAY_OF_WEEK FROM
      ... ) </code>Returns an integer value in the range of 1-7. The first
      day of the week is Sunday. (JDBC)</p>
<a name="N13D03" class="indexterm"></a>
<p>
<span class="bold"><strong>DAYOFYEAR</strong></span>
</p>
<p>
<code class="literal">DAYOFYEAR ( &lt;datetime value expr&gt;
      )</code>
</p>
<p>This function is equivalent to <code class="literal">EXTRACT ( DAY_OF_YEAR FROM
      ... ) </code>Returns an integer value in the range of 1-366.
      (JDBC)</p>
<a name="N13D14" class="indexterm"></a>
<p>
<span class="bold"><strong>DAYS</strong></span>
</p>
<p>
<code class="literal">DAYS ( &lt;datetime value expr&gt; ) </code>
</p>
<p>The <code class="literal">&lt;datetime value expr&gt; </code>is of DATE or
      TIMESTAMP type. This function returns the DAY number since the first day
      of the calendar. The first day is numbered 1. (HyperSQL)</p>
<a name="N13D25" class="indexterm"></a>
<p>
<span class="bold"><strong>HOUR</strong></span>
</p>
<p>
<code class="literal">HOUR ( &lt;datetime value expr&gt; )</code>
</p>
<p>This function is equivalent to <code class="literal">EXTRACT ( HOUR FROM ... )
      </code>Returns an integer value in the range of 0-23. (JDBC)</p>
<a name="N13D36" class="indexterm"></a>
<p>
<span class="bold"><strong>MINUTE</strong></span>
</p>
<p>
<code class="literal">MINUTE ( &lt;datetime value expr&gt; )</code>
</p>
<p>This function is equivalent to<code class="literal"> EXTRACT ( MINUTE FROM ...
      ) </code>Returns an integer value in the range of 0 - 59.
      (JDBC)</p>
<a name="N13D47" class="indexterm"></a>
<p>
<span class="bold"><strong>MONTH</strong></span>
</p>
<p>
<code class="literal">MONTH ( &lt;datetime value expr&gt; )</code>
</p>
<p>This function is equivalent to <code class="literal">EXTRACT ( MONTH FROM ... )
      </code>Returns an integer value in the range of 1-12. (JDBC)</p>
<a name="N13D58" class="indexterm"></a>
<p>
<span class="bold"><strong>MONTHNAME</strong></span>
</p>
<p>
<code class="literal">MONTHNAME ( &lt;datetime value expr&gt;
      )</code>
</p>
<p>This function is equivalent to <code class="literal">EXTRACT ( NAME_OF_MONTH
      FROM ... ) </code>Returns a string in the range of January -
      December. (JDBC)</p>
<a name="N13D69" class="indexterm"></a>
<p>
<span class="bold"><strong>QUARTER</strong></span>
</p>
<p>
<code class="literal">QUARTER ( &lt;datetime value expr&gt; )</code>
</p>
<p>This function is equivalent to <code class="literal">EXTRACT ( QUARTER FROM ...
      ) </code>Returns an integer in the range of 1 - 4. (JDBC)</p>
<a name="N13D7A" class="indexterm"></a>
<p>
<span class="bold"><strong>SECOND</strong></span>
</p>
<p>
<code class="literal">SECOND ( &lt;datetime value expr&gt; )</code>
</p>
<p>This function is equivalent to <code class="literal">EXTRACT ( SECOND FROM ...
      ) </code>Returns an integer or decimal in the range of 0 - 59, with
      the same precision as the &lt;datetime value expr&gt;. (JDBC)</p>
<a name="N13D8B" class="indexterm"></a>
<p>
<span class="bold"><strong>SECONDS_SINCE_MIDNIGHT</strong></span>
</p>
<p>
<code class="literal">SECONDS_SINCE_MIDNIGHT ( &lt;datetime value expr&gt;
      )</code>
</p>
<p>This function is equivalent to<code class="literal"> EXTRACT (
      SECONDS_SINCE_MIDNIGHT FROM ... ) </code>Returns an integer in the
      range of 0 - 86399. (HyperSQL)</p>
<a name="N13D9C" class="indexterm"></a>
<p>
<span class="bold"><strong>UNIX_TIMESTAMP</strong></span>
</p>
<p>
<code class="literal">UNIX_TIMESTAMP ( [ &lt;datetime value expression&gt; ] )
      </code>
</p>
<p>This function returns a BIGINT value. With no parameter, it
      returns the number of seconds since 1970-01-01. With a DATE or TIMESTAMP
      parameter, it converts the argument into number of seconds since
      1970-01-01. The TIMESTAMP ( &lt;num value expression&gt; function
      returns a TIMESTAMP from a Unix timestamp. (HyperSQL)</p>
<a name="N13DAA" class="indexterm"></a>
<p>
<span class="bold"><strong>WEEK</strong></span>
</p>
<p>
<code class="literal">WEEK ( &lt;datetime value expr&gt; )</code>
</p>
<p>This function is equivalent to<code class="literal"> EXTRACT ( WEEK_OF_YEAR
      FROM ... ) </code>Returns an integer in the range of 1 - 54.
      (JDBC)</p>
<a name="N13DBB" class="indexterm"></a>
<p>
<span class="bold"><strong>YEAR</strong></span>
</p>
<p>
<code class="literal">YEAR ( &lt;datetime value expr&gt; )</code>
</p>
<p>This function is equivalent to<code class="literal"> EXTRACT ( YEAR FROM ... )
      </code>Returns an integer in the range of 1 - 9999. (JDBC)</p>
<a name="N13DCC" class="indexterm"></a>
<p>
<span class="bold"><strong>EXTRACT</strong></span>
</p>
<p>
<code class="literal">EXTRACT ( &lt;extract field&gt; FROM &lt;extract
      source&gt; )</code>
</p>
<p>
<code class="literal">&lt;extract field&gt; ::= YEAR | MONTH | DAY | HOUR |
      MINUTE | DAY_OF_WEEK | WEEK_OF_YEAR | QUARTER | DAY_OF_YEAR |
      DAY_OF_MONTH |</code>
</p>
<p>
<code class="literal">TIMEZONE_HOUR | TIMEZONE_MINUTE | SECOND |
      SECONDS_SINCE_MIDNIGHT |</code>
</p>
<p>
<code class="literal">DAY_NAME | MONTH_NAME</code>
</p>
<p>
<code class="literal">&lt;extract source&gt; ::= &lt;datetime value expr&gt; |
      &lt;interval value expr&gt;</code>
</p>
<p>The EXTRACT function returns a field or element of the
      <code class="literal">&lt;extract source&gt;</code>. The <code class="literal">&lt;extract
      source&gt;</code> is a datetime or interval expression. The type of
      the return value is BIGINT for most of the<code class="literal"> &lt;extract
      field&gt;</code> options. The exceptions is <code class="literal">SECOND
      </code>where a DECIMAL value is returned which has the same precision
      as the datetime or interval expression. The field values
      <code class="literal">DAY_NAME </code>or<code class="literal"> MONTH_NAME </code>result in a
      character string. When <code class="literal">MONTH_NAME</code> is specified, a
      string in the range January - December is returned. When
      <code class="literal">DAY_NAME </code>is specified, a string in the range Sunday
      -Saturday is returned.</p>
<p>If the <code class="literal">&lt;extract source&gt;</code> is <code class="literal">FROM
      &lt;datetime value expr&gt;</code>, different groups of
      <code class="literal">&lt;extract source&gt;</code> can be used depending on the
      data type of the expression. The <code class="literal">TIMEZONE_HOUR |
      TIMEZONE_MINUTE</code> options are valid only for TIME WITH TIMEZONE
      and TIMESTAMP WITH TIMEZONE data types. The <code class="literal">HOUR | MINUTE |
      SECOND | SECONDS_MIDNIGHT</code> options, are valid for TIME and
      TIMESTAMP types. The rest of the fields are valid for DATE and TIMESTAMP
      types.</p>
<p>If the <code class="literal">&lt;extract source&gt;</code> is <code class="literal">FROM
      &lt;interval value expr&gt;</code>, the <code class="literal">&lt;extract
      field&gt;</code> must be one of the fields of the INTERVAL type of
      the expressions. The <code class="literal">YEAR | MONTH</code> options may be
      valid for INTERVAL types based on months. The <code class="literal">DAY | HOUR |
      MINUTE | SECOND | SECONDS_MIDNIGHT</code> options may be valid for
      INTERVAL types based on seconds. For example,<code class="literal"> DAY | HOUR |
      MINUTE</code> are the only valid fields for the INTERVAL DAY TO
      MINUTE data type. (Foundation with HyperSQL extensions)</p>
</div>
<div class="section" title="Functions for Datetime Arithmetic">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="bfc_datetime_arithmetic"></a>Functions for Datetime Arithmetic</h3>
</div>
</div>
</div>
<a name="N13E27" class="indexterm"></a>
<p>
<span class="bold"><strong>ADD_MONTHS</strong></span>
</p>
<p>
<code class="literal">ADD_MONTHS ( &lt;datetime value expr&gt;, &lt;numeric
      value expr&gt;)</code>
</p>
<p>This function is similar but different to simple addition a MONTH
      interval to a datetime value. The SQL Standard expression,
      <code class="literal">&lt;datetime value expr&gt; + n MONTH</code>, when used with
      the last day of a short month such as February, returns a date that has
      the same day of the month in the target month. The
      <code class="literal">ADD_MONTHS</code> function adjusts the target day to the
      last day of the target month. For all other days, the behaviour is the
      same. This function always returns a TIMESTAMP(0) value, regardless of
      the type of the argument. (HyperSQL)</p>
<p>The example below compares the output of the function and the
      expression.</p>
<pre class="programlisting"> VALUES ADD_MONTHS ( DATE '2012-02-29' , 1), DATE '2012-02-29' + 1 MONTH

 C1                  C2         
 ------------------- ---------- 
 2012-03-31 00:00:00 2012-03-29 
</pre>
<a name="N13E40" class="indexterm"></a>
<p>
<span class="bold"><strong>LAST_DAY</strong></span>
</p>
<p>
<code class="literal">LAST_DAY ( &lt;datetime value expr&gt; )</code>
</p>
<p>Returns the last day of the month for the given argument,
      preserving the year, month, hour, minute and secend fields of the date.
      The type of the result is always TIMESTAMP(0). (HyperSQL)</p>
<pre class="programlisting"> VALUES LAST_DAY ( TIMESTAMP '2012-02-14 12:30:44')

 C1                  
 ------------------- 
 2012-02-29 12:30:44 
</pre>
<a name="N13E51" class="indexterm"></a>
<p>
<span class="bold"><strong>MONTHS_BETWEEN</strong></span>
</p>
<p>
<code class="literal">MONTHS_BETWEEN ( &lt;datetime value expr1&gt; ,
      &lt;datetime value expr2&gt; )</code>
</p>
<p>Returns the a number (not an INTERVAL) possibly with a fraction,
      representing the number of months between two days. If both dates have
      the same day of month, or are on the last day of the month, the result
      is an exact numeric. Otherwise, the fraction is calculated base on 31
      days per month. You can cast the resulting value into INTERVAL MONTH and
      use it for datetime arithmetic. (HyperSQL)</p>
<pre class="programlisting"> VALUES MONTHS_BETWEEN ( TIMESTAMP '2013-02-14 12:30:44', TIMESTAMP '2012-01-04 12:30:44')

 C1                                  
 ----------------------------------- 
 13.32258064516129000000000000000000 
</pre>
<a name="N13E62" class="indexterm"></a>
<p>
<span class="bold"><strong>TIMESTAMPADD</strong></span>
</p>
<p>
<code class="literal">TIMESTAMPADD ( &lt;tsi datetime field&gt;, &lt;numeric
      value expression&gt;, &lt;datetime value expr&gt;)</code>
</p>
<a name="N13E6E" class="indexterm"></a>
<p>
<span class="bold"><strong>TIMESTAMPDIFF</strong></span>
</p>
<p>
<code class="literal">TIMESTAMPDIFF ( &lt;tsi datetime field&gt;, &lt;datetime
      value expr 1&gt;, &lt;datetime value expr 2&gt;)</code>
</p>
<p>
<code class="literal">&lt;tsi datetime field&gt; ::= SQL_TSI_FRAC_SECOND |
      SQL_TSI_SECOND | SQL_TSI_MINUTE | SQL_TSI_HOUR | SQL_TSI_DAY |
      SQL_TSI_WEEK | SQL_TSI_MONTH | SQL_TSI_QUARTER |
      SQL_TSI_YEAR</code>
</p>
<p>HyperSQL supports full SQL Standard datetime features. It supports
      adding integers representing units of time directly to datetime values
      using the arithmetic plus operator. It also supports subtracting one
      <code class="literal">&lt;datetime value expr&gt;</code> from another in the given
      units of date or time using the minus operator. An example of
      <code class="literal">&lt;datetime value expr&gt; + &lt;numeric value expression&gt;
      &lt;datetime field&gt; </code>is <code class="literal">LOCALTIMESTAMP + 5
      DAY</code>. An example of <code class="literal">( &lt;datetime value expr&gt; -
      &lt;numeric value expression&gt; ) &lt;datetime field&gt; </code>is
      <code class="literal">(CURRENT_DATE - DATE '2008-08-8') MONTH </code>which returns
      the number of calendar months between the two dates.</p>
<p>The two JDBC functions, <code class="literal">TIMESTAMPADD </code>and
      <code class="literal">TIMESTAMPDIFF</code> perform the same function as above SQL
      expressions. The field names are keywords and are different from those
      used in the EXTRACT functions. These names are valid for use only when
      calling these two functions. The return value for TIMESTAMPADD is of the
      same type as the datetime argument used. The return type for
      TIMESTAMPDIFF is always BIGINT, regardless of the type of arguments. The
      two datetime arguments of TIMESTAMPDIFF should be of the same type. The
      TIME type is not supported for the arguments to these functions.</p>
<p>
<code class="literal">TIMESTAMPDIFF</code> is evaluated as &lt;datetime
      value expr 2&gt; - &lt;datetime value expr 1&gt;. (JDBC)</p>
<pre class="programlisting"> TIMESTAMPADD ( SQL_TSI_MONTH, 3, DATE '2008-11-22' )

 TIMESTAMPDIFF ( SQL_TSI_HOUR, TIMESTAMP '2008-11-20 20:30:40', TIMESTAMP '2008-11-21 21:30:40' )
</pre>
<a name="N13E9C" class="indexterm"></a>
<p>
<span class="bold"><strong>DATE_ADD</strong></span>
</p>
<p>
<code class="literal">DATE_ADD ( &lt;datetime value expr&gt; , &lt;interval
      value expr&gt; )</code>
</p>
<a name="N13EA8" class="indexterm"></a>
<p>
<span class="bold"><strong>DATE_SUB</strong></span>
</p>
<p>
<code class="literal">DATE_SUB ( &lt;datetime value expr&gt; , &lt;interval
      value expr&gt; )</code>
</p>
<p>These functions are equivalent to arithmetic addition and
      subtraction, &lt;datetime value expr&gt; + &lt;interval value expr&gt;
      and &lt;datetime value expr&gt; - &lt;interval value expr&gt;. The
      functions are provided for compatibility with other databases. The
      supported interval units are the standard SQL interval unit listed in
      other chapters of this guide. The TIME type is supported for the
      argument to these functions. (HyperSQL)</p>
<pre class="programlisting"> DATE_ADD ( DATE '2008-11-22', INTERVAL 3 MONTH )

 DATE_SUB ( TIMESTAMP '2008-11-22 20:30:40', INTERVAL 20 HOUR )
</pre>
<a name="N13EB8" class="indexterm"></a>
<p>
<span class="bold"><strong>DATEADD</strong></span>
</p>
<p>
<code class="literal">DATEADD ( &lt;field&gt;, &lt;numeric value expr&gt;,
      &lt;datetime value expr&gt; )</code>
</p>
<a name="N13EC4" class="indexterm"></a>
<p>
<span class="bold"><strong>DATEDIFF</strong></span>
</p>
<p>
<code class="literal">DATEDIFF ( &lt;field&gt;, &lt;datetime value expr 1&gt;,
      &lt;datetime value expr 2&gt; )</code>
</p>
<p>
<code class="literal">&lt;field&gt; ::= 'yy' | 'year' | 'mm' | 'month' | 'dd' |
      'day' | 'hh' | 'hour' | 'mi' | 'minute' | 'ss' | 'second' | 'ms' |
      'millisecond'</code>
</p>
<p>The DATEADD and DATEDIFF functions are alternatives to
      TIMESTAMPADD and TIMESTAMPDIFF, with fewer available field options. The
      field names are specified as strings, rather than keywords. The fields
      translate to YEAR, MONTH, DAY, HOUR, MINUTE, SECOND and MILLISECOND.
      <code class="literal">DATEDIFF</code> is evaluated as &lt;datetime value expr
      2&gt; - &lt;datetime value expr 1&gt;. (HyperSQL}</p>
<p>
<code class="literal">DATEDIFF ( &lt;datetime value expr 1&gt;, &lt;datetime
      value expr 2&gt; )</code>
</p>
<p>This special form of <code class="literal">DATEDIFF</code> does not have a
      field parameter and return the number of days between two dates. This
      form is evaluated as <code class="literal">&lt;datetime value expr 1&gt; -
      &lt;datetime value expr 2&gt;</code>, which is different from the
      main form. This form is compatible with some other database engines. The
      TIME type is not supported for the arguments to these functions.
      (HyperSQL}</p>
<pre class="programlisting"> DATEADD ( 'month', 3, DATE '2008-11-22' )

 DATEDIFF ( 'hour', TIMESTAMP '2008-11-22 20:30:40', TIMESTAMP '2008-11-22 00:30:40' )
</pre>
<a name="N13EE5" class="indexterm"></a>
<p>
<span class="bold"><strong>ROUND</strong></span>
</p>
<p>
<code class="literal">ROUND ( &lt;datetime value expr&gt; [ , &lt;char value
      expr&gt; ] ) </code>
</p>
<p>The <code class="literal">&lt;datetime value expr&gt; </code>is of DATE,
      TIME or TIMESTAMP type. The <code class="literal">&lt;char value expr&gt;</code>
      is a format string for YEAR, MONTH, WEEK OF YEAR, DAY, HOUR, MINUTE or
      SECOND as listed in the table for TO_CHAR and TO_DATE format elements
      (see below). The datetime value is rounded up or down after the
      specified field and the rest of the fields to the right are set to one
      for MONTH and DAY, or zero, for the rest of the fields. For example
      rounding a timestamp value on the DAY field results in midnight the same
      date or midnight the next day if the time is at or after 12 noon. If the
      second argument is omitted, the datetime value is rounded to the nearest
      day. (HyperSQL)</p>
<a name="N13EF9" class="indexterm"></a>
<p>
<span class="bold"><strong>TRUNC</strong></span>
</p>
<p>
<code class="literal">TRUNC ( &lt;datetime value expr&gt; [ , &lt;char value
      expr&gt; ] ) </code>
</p>
<p>Similar to the ROUND function, the <code class="literal">&lt;num value expr&gt;
      </code>is of DATE, TIME or TIMESTAMP type. The <code class="literal">&lt;char
      value expr&gt;</code> is a format string (such as 'YY' or 'MM') for
      YEAR, MONTH, WEEK OF YEAR, DAY, HOUR, MINUTE or SECOND as listed in the
      table for TO_CHAR and TO_DATE format elements (see below). The datetime
      value is truncated after the specified field and the rest of the fields
      to the right are set to one for MONTH and DAY, or zero, for the rest of
      the fields. For example applying TRUNC to a timestamp value on the DAY
      field results in midnight the same date. Examples of ROUND and TRUNC
      functions are given below. If the second argument is omitted, the
      datetime value is truncated to midnight the same date. (HyperSQL)</p>
<pre class="programlisting"> ROUND ( TIMESTAMP'2008-08-01 20:30:40', 'YYYY' )

 TIMESTAMP '2009-01-01 00:00:00'

 TRUNC ( TIMESTAMP'2008-08-01 20:30:40', 'YYYY' )

 TIMESTAMP '2008-01-01 00:00:00'
</pre>
</div>
<div class="section" title="Functions to Convert or Format a Datetime">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="bfc_datetime_format"></a>Functions to Convert or Format a Datetime</h3>
</div>
</div>
</div>
<a name="N13F13" class="indexterm"></a>
<p>
<span class="bold"><strong>TIMESTAMP</strong></span>
</p>
<p>TIMESTAMP ( &lt;num value expr&gt; )</p>
<p>TIMESTAMP ( &lt;char value expr&gt; )</p>
<p>
<code class="literal">TIMESTAMP ( &lt;char value expr&gt;, &lt;char value
      expr&gt; )</code>
</p>
<p>
<code class="literal">TIMESTAMP ( &lt;date value expr&gt;, &lt;time value
      expr&gt; )</code>
</p>
<p>This function translates the arguments into a TIMESTAMP WIHOUT
      TIME ZONE value.</p>
<p>When the single argument is a numeric value, it is interpreted as
      a Unix timestamp in seconds.</p>
<p>When the single argument is a formatted date or timestamp string,
      it is translated to a TIMESTAMP.</p>
<p>When two arguments are used, the first argument is the date part
      and the second argument is the time part of the returned TIMESTAMP
      value. An example, including the result, is given below:</p>
<pre class="programlisting"> TIMESTAMP ( '2008-11-22', '20:30:40' )

 TIMESTAMP '2008-11-22 20:30:40.000000'
</pre>
<a name="N13F30" class="indexterm"></a>
<p>
<span class="bold"><strong>TIMESTAMP_WITH_ZONE</strong></span>
</p>
<p>TIMESTAMP_WITH_ZONE ( &lt;num value expr&gt; )</p>
<p>TIMESTAMP_WITH_ZONE ( &lt;char value expr&gt; )</p>
<p>This function translates the arguments into a TIMESTAMP WITH TIME
      ZONE value.</p>
<p>When the single argument is a numeric value, it is interpreted as
      a Unix timestamp in seconds.</p>
<p>When the single argument is TIMESTAMP, it is converted to
      TIMESTAMP WITH TIME ZONE.</p>
<p>The time zone of the returned value is the local time zone at the
      time of the timestamp argument. This accounts for daylight saving times.
      For example, if the local time zone was +4:00 at the time of the given
      Unix timestamp, the returned value is local timestamp at the time with
      time zone +4:00.</p>
<a name="N13F45" class="indexterm"></a>
<p>
<span class="bold"><strong>TO_CHAR</strong></span>
</p>
<p>
<code class="literal">TO_CHAR ( &lt;datetime value expr&gt;, &lt;char value
      expr&gt; )</code>
</p>
<p>This function formats a datetime or numeric value to the format
      given in the second argument. The format string can contain pattern
      elements from the list given below, plus punctuation and space
      characters. An example, including the result, is given below:</p>
<pre class="programlisting"> TO_CHAR ( TIMESTAMP'2008-02-01 20:30:40', 'YYYY BC MONTH, DAY HH' )

 2008 AD February, Friday 8

 TO_CHAR ( TIMESTAMP'2008-02-01 20:30:40', '"The Date is" YYYY BC MONTH, DAY HH' )

 The Date is 2008 AD February, Friday 8
</pre>
<p>The format is internally translated to a
      <code class="classname">java.text.SimpleDateFormat</code> format string.
      Separator characters (space, comma, period, hyphen, colon, semicolon,
      forward slash) can be included between the pattern elements. Unsupported
      format strings should not be used. You can include a string literal
      inside the format string by enclosing it in double quotes (see the
      second example above). (HyperSQL)</p>
<a name="N13F5A" class="indexterm"></a>
<p>
<span class="bold"><strong>TO_DATE</strong></span>
</p>
<p>
<code class="literal">TO_DATE ( &lt;char value expr&gt;, &lt;char value
      expr&gt; )</code>
</p>
<p>This function translates a formatted datetime sting to a
      TIMESTAMP(0) according to the format given in the second argument. See
      TO_TIMESTAMP below for further details.</p>
<a name="N13F68" class="indexterm"></a>
<p>
<span class="bold"><strong>TO_TIMESTAMP</strong></span>
</p>
<p>
<code class="literal">TO_TIMESTAMP ( &lt;char value expr&gt;, &lt;char value
      expr&gt; )</code>
</p>
<p>This function translates a formatted datetime sting to a
      TIMESTAMP(6) according to the format given in the second argument. The
      format string can contain pattern elements from the list given below,
      plus punctuation and space characters. The pattern should contain all
      the necessary fields to construct a date, including, year, month, day of
      month, etc. The returned timestamp can then be cast into DATE or TIME
      types if necessary. An example, including the result, is given
      below:</p>
<pre class="programlisting"> TO_TIMESTAMP ( '22/11/2008 20:30:40', 'DD/MM/YYYY HH:MI:SS' )

 TIMESTAMP '2008-11-22 20:30:40.000000'
</pre>
<p>The format strings that can be used for TO_DATE and TO_TIMESTAMP
      are more restrictive than those used for TO_CHAR, because the format
      string must contain the elements needed to build a full DATE or
      TIMESTAMP value. For example, you cannot use the 'WW', 'W', 'HH' or
      'HH12' format elements with TO_DATE or TO_TIMESTAMP</p>
<p>The format is internally translated to a
      <code class="classname">java.text.SimpleDateFormat</code> format string.
      Unsupported format strings should not be used. With TO_CHAR, you can
      include a string literal inside the format string by enclosing it in
      double quotes. (HyperSQL)</p>
<p>The supported format components are all uppercase as
      follows:</p>
<div class="table">
<a name="N13F81"></a>
<p class="title">
<b>Table&nbsp;10.1.&nbsp;TO_CHAR, TO_DATE and TO_TIMESTAMP format elements</b>
</p>
<div class="table-contents">
<table summary="TO_CHAR, TO_DATE and TO_TIMESTAMP format elements" cellspacing="0" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="5cm">
<col>
</colgroup>
<tbody>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="literal">BC | B.C. | AD | A.D.</code></td><td style="border-bottom: 0.5pt solid ; ">Returns <code class="literal">AD</code> for common era and
              <code class="literal">BC</code> for before common era</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="literal">RRRR</code></td><td style="border-bottom: 0.5pt solid ; ">
<p>4-digit year</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="literal">YYYY</code></td><td style="border-bottom: 0.5pt solid ; ">
<p>4-digit year</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="literal">IYYY</code></td><td style="border-bottom: 0.5pt solid ; ">
<p>4-digit year, corresponding to ISO week of the
              year. The reported year for the last few days of the calendar
              year may be the next year.</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="literal">YY</code></td><td style="border-bottom: 0.5pt solid ; ">
<p>2 digit year</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="literal">IY</code></td><td style="border-bottom: 0.5pt solid ; ">
<p>2 digit year, corresponding to ISO week of the year
              </p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="literal">MM</code></td><td style="border-bottom: 0.5pt solid ; ">
<p>Month (01-12)</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="literal">MON</code></td><td style="border-bottom: 0.5pt solid ; ">
<p>Short three-letter name of month</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="literal">MONTH</code></td><td style="border-bottom: 0.5pt solid ; ">
<p>Name of month</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="literal">WW</code></td><td style="border-bottom: 0.5pt solid ; ">
<p>Week of year (1-53) where week 1 starts on the
              first day of the year and continues to the seventh day of the
              year (not a calendar week).</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="literal">W</code></td><td style="border-bottom: 0.5pt solid ; ">
<p>Week of month (1-5) where week 1 starts on the
              first day of the month and ends on the seventh (not a calendar
              week).</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="literal">IW</code></td><td style="border-bottom: 0.5pt solid ; ">
<p>Week of year (1-52 or 1-53) based on the ISO
              standard. Week starts on Monday. The first week may start near
              the end of previous year.</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="literal">DAY</code></td><td style="border-bottom: 0.5pt solid ; ">
<p>Name of day.</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="literal">DD</code></td><td style="border-bottom: 0.5pt solid ; ">
<p>Day of month (01-31).</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="literal">DDD</code></td><td style="border-bottom: 0.5pt solid ; ">
<p>Day of year (1-366).</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="literal">DY</code></td><td style="border-bottom: 0.5pt solid ; ">
<p>Short three-letter name of day.</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="literal">HH</code></td><td style="border-bottom: 0.5pt solid ; ">
<p>Hour of day (00-11).</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="literal">HH12</code></td><td style="border-bottom: 0.5pt solid ; ">
<p>Hour of day (00-11).</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="literal">HH24</code></td><td style="border-bottom: 0.5pt solid ; ">
<p>Hour of day (00-23).</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="literal">MI</code></td><td style="border-bottom: 0.5pt solid ; ">
<p>Minute (00-59).</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="literal">SS</code></td><td style="border-bottom: 0.5pt solid ; ">
<p>Second (00-59).</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; "><code class="literal">FF</code></td><td style="">
<p>Fractional seconds.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
</div>
</div>
<div class="section" title="Array Functions">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="bfc_array_functions"></a>Array Functions</h2>
</div>
</div>
</div>
<p>Array functions are specialised functions with ARRAY parameters or
    return values. For the ARRAY_AGG aggregate function, see the <a class="link" href="#dataaccess-chapt" title="Chapter&nbsp;7.&nbsp;Data Access and Change">Data Access and Change</a>
    chapter.</p>
<a name="N14036" class="indexterm"></a>
<p>
<span class="bold"><strong>CARDINALITY</strong></span>
</p>
<p>
<code class="literal">CARDINALITY( &lt;array value expr&gt; )</code>
</p>
<p>Returns the element count for the given array argument.
    (Foundation)</p>
<a name="N14044" class="indexterm"></a>
<p>
<span class="bold"><strong>MAX_CARDINALITY</strong></span>
</p>
<p>
<code class="literal">MAX_CARDINALITY( &lt;array value expr&gt;
    )</code>
</p>
<p>Returns the maximum allowed element count for the given array
    argument. (Foundation)</p>
<a name="N14052" class="indexterm"></a>
<p>
<span class="bold"><strong>POSITION_ARRAY</strong></span>
</p>
<p>
<code class="literal">POSITION_ARRAY( &lt;value expression&gt; IN &lt;array value
    expr&gt; [ FROM &lt;int value expr&gt; ] )</code>
</p>
<p>Returns the position of the first match for the <code class="literal">&lt;value
    expression&gt;</code> in the array. By default the search starts from
    the beginning of the array. The optional <code class="literal">&lt;int value
    expr&gt;</code> specifies the start position. Positions are counted
    from 1. Returns zero if no match is found. (HyperSQL)</p>
<a name="N14066" class="indexterm"></a>
<p>
<span class="bold"><strong>SORT_ARRAY</strong></span>
</p>
<p>
<code class="literal">SORT_ARRAY( &lt;array value expr&gt; [ { ASC | DESC } ] [
    NULLS { FIRST | LAST } ] )</code>
</p>
<p>Returns a sorted copy of the array. By default, sort is performed in
    ascending order and NULL elements are sorted first. (HyperSQL)</p>
<a name="N14074" class="indexterm"></a>
<p>
<span class="bold"><strong>TRIM_ARRAY</strong></span>
</p>
<p>
<code class="literal">TRIM_ARRAY( &lt;array value expr&gt;, &lt;num value
    expr&gt; )</code>
</p>
<p>Returns a new array that contains the elements of the
    <code class="literal">&lt;array value expr&gt;</code> minus the number of elements
    specified by the <code class="literal">&lt;num value expr&gt;. </code>Elements are
    discarded from the end of the array. (Foundation)</p>
<a name="N14088" class="indexterm"></a>
<p>
<span class="bold"><strong>SEQUENCE_ARRAY</strong></span>
</p>
<p>
<code class="literal">SEQUENCE_ARRAY( &lt;value expr 1&gt;, &lt;value expr 2&gt;,
    &lt;value expr 3 )</code>
</p>
<p>Returns a new array that contains a sequence of values. The
    <code class="literal">&lt;value expr 1&gt;</code> is the lower bound of the range.
    The <code class="literal">&lt;value expr 2&gt;</code> is the upper bound of the
    range. The <code class="literal">&lt;value expr 3&gt;</code> is the increment. The
    elments of the array are within the inclusive range. The first element is
    <code class="literal">&lt;value expr 1&gt;</code> and each subsequent element is the
    sum of the previous element and the increment. If the increment is zero,
    only the first element is returned. When the increment is negative, the
    lower bound should be larger than the upper bound. The type of the
    arguments can be all number types, or a datetime range and an interval for
    the third argument (HyperSQL)</p>
<p>In the examples below, a number sequence and a date sequence are
    shown. The UNNEST table expression is used to form a table from the
    array.</p>
<pre class="programlisting"> SEQUENCE_ARRAY(0, 100, 5)

 ARRAY[0,5,10,15,20,25,30,35,40,45,50,55,60,65,70,75,80,85,90,95,100] 

 SELECT * FROM UNNEST(SEQUENCE_ARRAY(10, 12, 1))

 C1 
 -- 
 10 
 11 
 12 

 SELECT * FROM UNNEST(SEQUENCE_ARRAY(CURRENT_DATE, CURRENT_DATE + 6 DAY, 1 DAY)) WITH ORDINALITY AS T(D, I) 

 D          I 
 ---------- - 
 2010-08-01 1 
 2010-08-02 2 
 2010-08-03 3 
 2010-08-04 4 
 2010-08-05 5 
 2010-08-06 6 
 2010-08-07 7

</pre>
</div>
<div class="section" title="General Functions">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="bfc_general_functions"></a>General Functions</h2>
</div>
</div>
</div>
<p>General functions can take different types of arguments. Some
    General Functions accept a variable number of arguments.</p>
<p>Also see the <a class="link" href="#dataaccess-chapt" title="Chapter&nbsp;7.&nbsp;Data Access and Change">Data Access and Change</a> chapter for SQL expressions that
    are similar to functions, for example CAST and NULLIF.</p>
<a name="N140B3" class="indexterm"></a>
<p>
<span class="bold"><strong>CASEWHEN</strong></span>
</p>
<p>
<code class="literal">CASEWHEN( &lt;boolean value expr&gt;, &lt;value expr 2&gt;,
    &lt;value expr 3&gt; )</code>
</p>
<p>If the <code class="literal">&lt;boolean value expr&gt;</code> is true,
    returns <code class="literal">&lt;value expr 2&gt;</code> otherwise returns
    <code class="literal">&lt;value expr 3&gt;. Use a CASE WHEN expression instead for more
    extensive capabilities and options.</code> CASE WHEN is documented in
    the <a class="link" href="#dataaccess-chapt" title="Chapter&nbsp;7.&nbsp;Data Access and Change">Data Access and Change</a> chapter. (HyperSQL)</p>
<a name="N140CF" class="indexterm"></a>
<p>
<span class="bold"><strong>COALESCE</strong></span>
</p>
<p>
<code class="literal">COALESCE( &lt;value expr 1&gt;, &lt;value expr 2&gt; [,
    ...] )</code>
</p>
<p>Returns <code class="literal">&lt;value expr 1&gt;</code> if it is not null,
    otherwise returns <code class="literal">&lt;value expr 2&gt;</code> if not null and
    so on. The type of both arguments must be comparable. (Foundation)</p>
<a name="N140E3" class="indexterm"></a>
<p>
<span class="bold"><strong>CONVERT</strong></span>
</p>
<p>
<code class="literal">CONVERT ( &lt;value expr&gt; , &lt;data type&gt;
    )</code>
</p>
<p>
<code class="literal">&lt;data type&gt; ::= { SQL_BIGINT | SQL_BINARY | SQL_BIT
    |SQL_BLOB | SQL_BOOLEAN | SQL_CHAR | SQL_CLOB | SQL_DATE | SQL_DECIMAL |
    SQL_DATALINK |SQL_DOUBLE | SQL_FLOAT | SQL_INTEGER | SQL_LONGVARBINARY |
    SQL_LONGNVARCHAR | SQL_LONGVARCHAR | SQL_NCHAR | SQL_NCLOB | SQL_NUMERIC |
    SQL_NVARCHAR | SQL_REAL | SQL_ROWID | SQL_SQLXML | SQL_SMALLINT | SQL_TIME
    | SQL_TIMESTAMP | SQL_TINYINT | SQL_VARBINARY | SQL_VARCHAR} [ (
    &lt;precision, length or scale parameters&gt; ) ]</code>
</p>
<p>The CONVERT function is a JDBC escape function, equivalent to the
    SQL standard CAST expression. It converts the <code class="literal">&lt;value
    expr&gt;</code> into the given <code class="literal">&lt;data type&gt;</code> and
    returns the value. The <code class="literal">&lt;data type&gt;</code> options are
    synthetic names made by prefixing type names with <code class="literal">SQL_</code>.
    Some of the <code class="literal">&lt;data type&gt;</code> options represent valid
    SQL types, but some are based on non-standard type names, namely
    <code class="literal">{ SQL_LONGNVARCHAR | SQL_LONGVARBINARY |SQL_LONGVARCHAR |
    SQL_TINYINT }</code>. None of the synthetic names can be used in any
    other context than the CONVERT function.</p>
<p>The definition of CONVERT in the JDBC Standard does not allow the
    precision, scale or length to be specified. This is required by the SQL
    standard for BINARY, BIT, BLOB, CHAR, CLOB, VARBINARY and VARCHAR types
    and is often needed for DECIMAL and NUMERIC. Defaults are used for
    precision.</p>
<p>HyperSQL also allows the use of real type names (without the
    <code class="literal">SQL_</code> prefix). In this usage, HyperSQL allows the use of
    precision, scale or length for the type definition when they are valid for
    the type definition.</p>
<p>When MS SQL Server compatibility mode is on, the parameters of
    CONVERT are switched and only the real type names with required precision,
    scale or length are allowed. (JDBC)</p>
<a name="N1410F" class="indexterm"></a>
<p>
<span class="bold"><strong>DECODE</strong></span>
</p>
<p>
<code class="literal">DECODE( &lt;value expr main&gt;, &lt;value expr match
    1&gt;, &lt;value expr result 1&gt; [...,] [, &lt;value expr default&gt;]
    )</code>
</p>
<p>DECODE takes at least 3 arguments. The <code class="literal">&lt;value expr
    main&gt;</code> is compared with <code class="literal">&lt;value expr match
    1&gt;</code> and if it matches, <code class="literal">&lt;value expr result
    1&gt;</code> is returned. If there are additional pairs of
    <code class="literal">&lt;value expr match n&gt;</code> and <code class="literal">&lt;value expr
    result n&gt;</code>, comparison is repeated until a match is found the
    result is returned. If no match is found, the <code class="literal">&lt;value expr
    default&gt;</code> is returned if it is specified, otherwise NULL is
    returned. The type of the return value is a combination of the types of
    the <code class="literal">&lt;value expr result ... &gt;</code> arguments.
    (HyperSQL)</p>
<a name="N14132" class="indexterm"></a>
<p>
<span class="bold"><strong>GREATEST</strong></span>
</p>
<p>
<code class="literal">GREATEST( &lt;value expr 1&gt;, [&lt;value expr ...&gt;,
    ...] )</code>
</p>
<p>The GREATEST function takes one or more arguments. It compares the
    arguments with each other and returns the greatest argument. The return
    type is the combined type of the arguments. Arguments can be of any type,
    so long as they are comparable. (HyperSQL)</p>
<a name="N14140" class="indexterm"></a>
<p>
<span class="bold"><strong>IFNULL</strong></span>
</p>
<a name="N14149" class="indexterm"></a>
<p>
<span class="bold"><strong>ISNULL</strong></span>
</p>
<p>
<code class="literal">IFNULL | ISNULL ( &lt;value expr 1&gt;, &lt;value expr
    2&gt; )</code>
</p>
<p>Returns <code class="literal">&lt;value expr 1&gt;</code> if it is not null,
    otherwise returns <code class="literal">&lt;value expr 2&gt;</code>. The type of the
    return value is the type of <code class="literal">&lt;value expr 1&gt;</code>.
    Almost equivalent to SQL Standard <code class="literal">COALESCE(&lt;value expr 1&gt;,
    &lt;value expr 2&gt;)</code> function, but without type modification.
    (JDBC)</p>
<a name="N14163" class="indexterm"></a>
<p>
<span class="bold"><strong>LEAST</strong></span>
</p>
<p>
<code class="literal">LEAST( &lt;value expr 1&gt;, [&lt;value expr ...&gt;, ...]
    )</code>
</p>
<p>The LEAST function takes one or more arguments. It compares the
    arguments with each other and returns the smallest argument. The return
    type is the combined type of the arguments. Arguments can be of any type,
    so long as they are comparable. (HyperSQL)</p>
<a name="N14171" class="indexterm"></a>
<p>
<span class="bold"><strong>LOAD_FILE</strong></span>
</p>
<p>
<code class="literal">LOAD_FILE ( &lt;char value expr 1&gt; [, &lt;char value
    expr 2&gt;] )</code>
</p>
<p>Returns a BLOB or CLOB containing the URL or file path specified in
    the first argument. If used with a single argument, the function returns a
    BLOB. If used with two arguments, the function returns a CLOB and the
    second argument is the character encoding of the file.</p>
<p>The file path is interpreted the same way as a TEXT TABLE source
    file location. The <code class="literal">hsqldb.allow_full_path</code> system
    property must be set <code class="literal">true</code> in order to access files
    outside the directory structure of the database files.</p>
<p>(HyperSQL)</p>
<a name="N14189" class="indexterm"></a>
<p>
<span class="bold"><strong>NULLIF</strong></span>
</p>
<p>
<code class="literal">NULLIF( &lt;value expr 1&gt;, &lt;value expr 2&gt;
    )</code>
</p>
<p>Returns <code class="literal">&lt;value expr 1&gt;</code> if it is not equal
    to <code class="literal">&lt;value expr 2&gt;</code>, otherwise returns null. The
    type of both arguments must be the same. This function is a shorthand for
    a specific CASE expression. (Foundation)</p>
<a name="N1419D" class="indexterm"></a>
<p>
<span class="bold"><strong>NVL</strong></span>
</p>
<p>
<code class="literal">NVL( &lt;value expr 1&gt;, &lt;value expr 2&gt;
    )</code>
</p>
<p>Returns <code class="literal">&lt;value expr 1&gt;</code> if it is not null,
    otherwise returns <code class="literal">&lt;value expr 2&gt;</code>. The type of the
    return value is the type of <code class="literal">&lt;value expr 1&gt;</code>. For
    example, if <code class="literal">&lt;value expr 1&gt;</code> is an INTEGER column
    and <code class="literal">&lt;value expr 2&gt;</code> is a DOUBLE constant, the
    return type is cast into INTEGER. This function is similar to IFNULL.
    (HyperSQL)</p>
<a name="N141BA" class="indexterm"></a>
<p>
<span class="bold"><strong>NVL2</strong></span>
</p>
<p>
<code class="literal">NVL2( &lt;value expr 1&gt;, &lt;value expr 2&gt;, &lt;value
    expr 3&gt; )</code>
</p>
<p>If <code class="literal">&lt;value expr 1&gt;</code> is not null, returns
    <code class="literal">&lt;value expr 2&gt;</code>, otherwise returns
    <code class="literal">&lt;value expr 3&gt;</code>. The type of the return value is
    the type of <code class="literal">&lt;value expr 2&gt;</code> unless it is null.
    (HyperSQL)</p>
<a name="N141D4" class="indexterm"></a>
<p>
<span class="bold"><strong>UUID</strong></span>
</p>
<p>
<code class="literal">UUID ( [ { &lt;char value expr&gt; | &lt;binary value
    expr&gt; ] } ) </code>
</p>
<p>With no parameter, this function returns a new UUID value as a 16
    byte binary value. With a UUID hexadecimal string argument, it returns the
    16 byte binary value of the UUID. With a 16 byte binary argument, it
    returns the formatted UUID character representation. (HyperSQL)</p>
</div>
<div class="section" title="System Functions">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="bfc_system_functions"></a>System Functions</h2>
</div>
</div>
</div>
<a name="N141E6" class="indexterm"></a>
<p>
<span class="bold"><strong>CRYPT_KEY</strong></span>
</p>
<p>
<code class="literal">CRYPT_KEY( &lt;value expr 1&gt;, &lt;value expr 2&gt;
    )</code>
</p>
<p>Returns a binary string representation of a cryptography key for the
    given cipher and cryptography provider. The cipher specification is
    specified by <code class="literal">&lt;value expr 1&gt;</code> and the provider by
    <code class="literal">&lt;value expr 2&gt;</code>. To use the default provider,
    specify null for <code class="literal">&lt;value expr 2&gt;</code>.
    (HyperSQL)</p>
<a name="N141FD" class="indexterm"></a>
<p>
<span class="bold"><strong>DIAGNOSTICS</strong></span>
</p>
<p>
<code class="literal">DIAGNOSTICS ( ROW_COUNT )</code>
</p>
<p>This is a convenience function for use instead of the <code class="literal">GET
    DIAGNOSTICS ...</code> statement. The argument specifies the name of
    the diagnostics variable. Currently the only supported variable is the
    <code class="literal">ROW_COUNT</code> variable. The function returns the row count
    returned by the last executed statement. The return value is 0 after most
    statements. Calling this function immediately after executing an INSERT,
    UPDATE, DELETE or MERGE statement returns the row count for the last
    statement, as it is returned by the JDBC statement. (HyperSQL)</p>
<a name="N14211" class="indexterm"></a>
<p>
<span class="bold"><strong>IDENTITY</strong></span>
</p>
<p>
<code class="literal">IDENTITY ()</code>
</p>
<p>Returns the last IDENTITY value inserted into a row by the current
    session. The statement, CALL IDENTITY() can be made after an INSERT
    statement that inserts a row into a table with an IDENTITY column. The
    CALL IDENTITY() statement returns the last IDENTITY value that was
    inserted into a table by the current session. Each session manages this
    function call separately and is not affected by inserts in other sessions.
    The statement can be executed as a direct statement or a prepared
    statement. (HyperSQL)</p>
<a name="N1421F" class="indexterm"></a>
<p>
<span class="bold"><strong>DATABASE</strong></span>
</p>
<p>
<code class="literal">DATABASE ()</code>
</p>
<p>Returns the file name (without directory information) of the
    database. (JDBC)</p>
<a name="N1422D" class="indexterm"></a>
<p>
<span class="bold"><strong>DATABASE_NAME</strong></span>
</p>
<p>
<code class="literal">DATABASE_NAME ()</code>
</p>
<p>Returns the database name. This name is a 16 character, uppercase
    string. It is generated as a string based on the timestamp of the creation
    of the database, for example HSQLDB32438AEAFB. The name can be redefined
    by an admin user but the new name must be all uppercase and 16 characters
    long. This name is used in log messages with external logging frameworks.
    (HyperSQL)</p>
<a name="N1423B" class="indexterm"></a>
<p>
<span class="bold"><strong>DATABASE_VERSION</strong></span>
</p>
<p>
<code class="literal">DATABASE_VERSION ()</code>
</p>
<p>Returns the full version string for the database engine. For
    example, 2.0.1. (JDBC)</p>
<a name="N14249" class="indexterm"></a>
<p>
<span class="bold"><strong>USER</strong></span>
</p>
<p>
<code class="literal">USER ()</code>
</p>
<p>Equivalent to the SQL function <code class="literal">CURRENT_USER</code>.
    (JDBC)</p>
<a name="N1425A" class="indexterm"></a>
<p>
<span class="bold"><strong>CURRENT_USER</strong></span>
</p>
<p>
<code class="literal">CURRENT_USER</code>
</p>
<a name="N14266" class="indexterm"></a>
<p>
<span class="bold"><strong>CURRENT_ROLE</strong></span>
</p>
<p>
<code class="literal">CURRENT_ROLE</code>
</p>
<a name="N14272" class="indexterm"></a>
<p>
<span class="bold"><strong>SESSION_USER</strong></span>
</p>
<p>
<code class="literal">SESSION_USER</code>
</p>
<a name="N1427E" class="indexterm"></a>
<p>
<span class="bold"><strong>SYSTEM_USER</strong></span>
</p>
<p>
<code class="literal">SYSTEM_USER</code>
</p>
<a name="N1428A" class="indexterm"></a>
<p>
<span class="bold"><strong>CURRENT_SCHEMA</strong></span>
</p>
<p>
<code class="literal">CURRENT_SCHEMA</code>
</p>
<a name="N14296" class="indexterm"></a>
<p>
<span class="bold"><strong>CURRENT_CATALOG</strong></span>
</p>
<p>
<code class="literal">CURRENT_CATALOG</code>
</p>
<p>These functions return the named current session attribute. They are
    all SQL Standard functions.</p>
<p>The CURRENT_USER is the user that connected to the database, or a
    user subsequently set by the SET AUTHORIZATION statement.</p>
<p>SESSION_USER is the same as CURRENT_USER</p>
<p>SYSTEM_USER is the user that connected to the database. It is not
    changed with any command until the session is closed.</p>
<p>CURRENT_SCHEMA is default schema of the user, or a schema
    subsequently set by the SET SCHEMA command.</p>
<p>CURRENT_CATALOG is always the same within a given HyperSQL database
    and indicates the name of the catalog.</p>
<a name="N142AE" class="indexterm"></a>
<p>
<span class="bold"><strong>IS_AUTOCOMMIT</strong></span>
</p>
<p>
<code class="literal">IS_AUTOCOMMIT()</code>
</p>
<p>Returns TRUE if the session is in autocommit mode. (HyperSQL)</p>
<a name="N142BC" class="indexterm"></a>
<p>
<span class="bold"><strong>IS_READONLY_SESSION</strong></span>
</p>
<p>
<code class="literal">IS_READONLY_SESSION()</code>
</p>
<p>Returns TRUE if the session is in read only mode. (HyperSQL)</p>
<a name="N142CA" class="indexterm"></a>
<p>
<span class="bold"><strong>IS_READONLY_DATABASE</strong></span>
</p>
<p>
<code class="literal">IS_READONLY_DATABASE()</code>
</p>
<p>Returns TRUE if the database is a read only database.
    (HyperSQL)</p>
<a name="N142D8" class="indexterm"></a>
<p>
<span class="bold"><strong>IS_READONLY_DATABASE_FILES</strong></span>
</p>
<p>
<code class="literal">IS_READONLY_DATABASE_FILES()</code>
</p>
<p>Returns TRUE if the database is a read-only files database. In this
    kind of database, it is possible to modify the data, but the changes are
    not persisted to the database files. (HyperSQL)</p>
<a name="N142E6" class="indexterm"></a>
<p>
<span class="bold"><strong>ISOLATION_LEVEL</strong></span>
</p>
<p>
<code class="literal">ISOLATION_LEVEL()</code>
</p>
<p>Returns the current transaction isolation level for the session.
    Returns either READ COMMITTED or SERIALIZABLE as a string.
    (HyperSQL)</p>
<a name="N142F4" class="indexterm"></a>
<p>
<span class="bold"><strong>SESSION_ID</strong></span>
</p>
<p>
<code class="literal">SESSION_ID()</code>
</p>
<p>Returns the id of the session as a BIGINT value. Each session id is
    unique during the operational lifetime of the database. Id's are restarted
    after a shutdown and restart. (HyperSQL)</p>
<a name="N14302" class="indexterm"></a>
<p>
<span class="bold"><strong>SESSION_ISOLATION_LEVEL</strong></span>
</p>
<p>
<code class="literal">SESSION_ISOLATION_LEVEL()</code>
</p>
<p>Returns the default transaction isolation level for the current
    session. Returns either READ COMMITTED or SERIALIZABLE as a string.
    (HyperSQL)</p>
<a name="N14310" class="indexterm"></a>
<p>
<span class="bold"><strong>DATABASE_ISOLATION_LEVEL</strong></span>
</p>
<p>
<code class="literal">DATABASE_ISOLATION_LEVEL()</code>
</p>
<p>Returns the default transaction isolation level for the database.
    Returns either READ COMMITTED or SERIALIZABLE as a string.
    (HyperSQL)</p>
<a name="N1431E" class="indexterm"></a>
<p>
<span class="bold"><strong>TRANSACTION_SIZE</strong></span>
</p>
<p>
<code class="literal">TRANSACTION_SIZE()</code>
</p>
<p>Returns the row change count for the current transaction. Each row
    change represents a row INSERT or a row DELETE operation. There will be a
    pair of row change operations for each row that is updated.</p>
<a name="N1432C" class="indexterm"></a>
<p>
<span class="bold"><strong>TRANSACTION_ID</strong></span>
</p>
<p>
<code class="literal">TRANSACTION_ID()</code>
</p>
<p>Returns the current transaction ID for the session as a BIGINT
    value. The database maintains a global incremental id which is allocated
    to new transactions and new actions (statement executions) in different
    sessions. This value is unique to the current transaction.
    (HyperSQL)</p>
<a name="N1433A" class="indexterm"></a>
<p>
<span class="bold"><strong>ACTION_ID</strong></span>
</p>
<p>
<code class="literal">ACTION_ID()</code>
</p>
<p>Returns the current action ID for the session as a BIGINT value. The
    database maintains a global incremental id which is allocated to new
    transactions and new actions (statement executions) in different sessions.
    This value is unique to the current action. (HyperSQL)</p>
<a name="N14348" class="indexterm"></a>
<p>
<span class="bold"><strong>TRANSACTION_CONTROL</strong></span>
</p>
<p>
<code class="literal">TRANSACTION_CONTROL()</code>
</p>
<p>Returns the current transaction model for the database. Returns
    LOCKS, MVLOCKS or MVCC as a string. (HyperSQL)</p>
<a name="N14356" class="indexterm"></a>
<p>
<span class="bold"><strong>LOB_ID</strong></span>
</p>
<p>
<code class="literal">LOB_ID( &lt;column reference&gt; )</code>
</p>
<p>Returns internal ID of a lob as a BIGINT value. Lob ID's are unique
    and never reused. The &lt;column reference&gt; is the name of the column
    (or variable, or argument) which is a CLOB or BLOB. Returns null if the
    value is null. (HyperSQL)</p>
<a name="N14364" class="indexterm"></a>
<p>
<span class="bold"><strong>ROWNUM</strong></span>
</p>
<p>
<code class="literal">ROWNUM()</code>
</p>
<a name="N14370" class="indexterm"></a>
<p>
<span class="bold"><strong>ROW_NUMBER</strong></span>
</p>
<p>
<code class="literal">ROW_NUMBER() OVER()</code>
</p>
<p>Returns the current row number (from 1) being processed in a select
    statement. This has the same semantics as the ROWNUM pseudo-column in
    Oracle syntax mode, but can be used in any syntax mode. The function is
    used in a SELECT of DELETE statement. The ROWNUM of a row is incremented
    as the rows are added to the result set. It is therefore possible to use a
    condition such as WHERE ROWNUM() &lt; 10, but not ROWNUM() &gt; 10 or
    ROWNUM = 10. The <code class="literal">ROW_NUMBER() OVER()</code> alternative
    performs the same function and is included for compatibility with other
    database engines.(HyperSQL)</p>
</div>
</div>
<div class="chapter" title="Chapter&nbsp;11.&nbsp;System Management">
<div class="titlepage">
<div>
<div>
<h2 class="title">
<a name="management-chapt"></a>Chapter&nbsp;11.&nbsp;System Management</h2>
</div>
<div>
<div class="authorgroup">
<div class="author">
<h3 class="author">
<span class="firstname">Fred</span> <span class="surname">Toussi</span>
</h3>
<div class="affiliation">
<span class="orgname">The HSQL Development Group<br>
</span>
</div>
</div>
</div>
</div>
<div>
<p class="releaseinfo">$Revision: 5321 $</p>
</div>
<div>
<div class="legalnotice" title="Legal Notice">
<a name="N143A5"></a>
<p>Copyright 2002-2012 Fred Toussi. Permission is granted to
      distribute this document without any alteration under the terms of the
      HSQLDB license. Additional permission is granted to the HSQL Development
      Group to distribute this document with or without alterations under the
      terms of the HSQLDB license.</p>
</div>
</div>
<div>
<p class="pubdate">2014-02-13 18:21:41-0500</p>
</div>
</div>
</div>
<div class="toc">
<p>
<b>Table of Contents</b>
</p>
<dl>
<dt>
<span class="section"><a href="#mtc_modes_tables">Mode of Operation and Tables</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#mtc_modes_operation">Mode of Operation</a></span>
</dt>
<dt>
<span class="section"><a href="#N143CE">Database Types</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_table_types">Tables</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_large_objects">Large Objects</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_deploy_context">Deployment context</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#mtc_acid_persistence">ACID, Persistence and Reliability</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#mtc_acid">Atomicity, Consistency, Isolation, Durability</a></span>
</dt>
<dt>
<span class="section"><a href="#N14491">System Operations</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#mtc_backup">Backing Up Database Catalogs</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#mtc_online_backup">Making Online Backups</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_offline_backup">Making Offline Backups</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_listing_backup">Examining Backups</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_restoring_backup">Restoring a Backup</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#mtc_encrypted_database">Encrypted Databases</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#mtc_encrypted_create">Creating and Accessing an Encrypted Database</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_encrypted_speed">Speed Considerations</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_encrypted_security">Security Considerations</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#mtc_monitoring_operation">Monitoring Database Operations</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#mtc_external_monitoring">External Statement Level Monitoring</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_internal_monitoring">Internal Statement Level Monitoring</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_internal_event_monitoring">Internal Event Monitoring</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_jdc_logging">Log4J and JDK logging</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_server_monitoring">Server Operation Monitoring</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#mtc_database_security">Database Security</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#mtc_security_defaults">Security Defaults</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_authentication_control">Authentication Control</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#mtc_compatibility_other">Compatibility with Other RDBMS</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#mtc_compatibility_postgres">PostgreSQL Compatibility</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_compatibility_mysql">MySQL Compatibility</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_compatibility_firebird">Firebird Compatibility</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_compatibility_derby">Apache Derby Compatibility</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_compatibility_oracle">Oracle Compatibility</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_compatibility_db2">DB2 Compatibility</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_compatibility_mssql">MS SQLServer and Sybase Compatibility</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#mtc_statements">Statements</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#mtc_system_operations">System Operations</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_database_settings">Database Settings</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_sql_settings">SQL Conformance Settings</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_cache_persistence">Cache, Persistence and Files Settings</a></span>
</dt>
<dt>
<span class="section"><a href="#mtc_authntication_settings">Authentication Settings</a></span>
</dt>
</dl>
</dd>
</dl>
</div>
<div class="section" title="Mode of Operation and Tables">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="mtc_modes_tables"></a>Mode of Operation and Tables</h2>
</div>
</div>
</div>
<p>HyperSQL has many modes of operation and features that allow it to
    be used in very different scenarios. Levels of memory usage, speed and
    accessibility by different applications are influenced by how HyperSQL is
    deployed.</p>
<div class="section" title="Mode of Operation">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="mtc_modes_operation"></a>Mode of Operation</h3>
</div>
</div>
</div>
<p>The decision to run HyperSQL as a separate server process or as an
      <em class="glossterm">in-process</em> database should be based on the
      following:</p>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>When HyperSQL is run as a server on a separate machine, it
            is isolated from hardware failures and crashes on the hosts
            running the application.</p>
</li>
<li class="listitem">
<p>When HyperSQL is run as a server on the same machine, it is
            isolated from application crashes and memory leaks.</p>
</li>
<li class="listitem">
<p>Server connections are slower than
            <em class="glossterm">in-process</em> connections due to the overhead
            of streaming the data for each JDBC call.</p>
</li>
<li class="listitem">
<p>You can reduce client/server traffic using SQL Stored
            procedures to reduce the number of JDBC execute calls.</p>
</li>
<li class="listitem">
<p>During development, it is better to use a Server with
            server.silent=false, which displays the statements sent to the
            server on the console window.</p>
</li>
<li class="listitem">
<p>To improve speed of execution for statements that are
            executed repeatedly, reuse a parameterized PreparedStatement for
            the lifetime of the connections.</p>
</li>
</ul>
</div>
</div>
<div class="section" title="Database Types">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="N143CE"></a>Database Types</h3>
</div>
</div>
</div>
<p>There are three types of database, <code class="literal">mem:</code>,
      <code class="literal">file:</code> and <code class="literal">res:</code>. The mem: type is
      stored all in memory and not persisted to file. The
      <code class="literal">file:</code> type is persisted to file. The
      <code class="literal">res:</code> type is also based on files, but the files are
      loaded from the classpath, similar to resource and class files. Changes
      to the data in <code class="literal">file:</code> databases are persisted, unless
      the database is <code class="literal">readonly</code>, or
      <code class="literal">files_readonly</code> (using optional property settings).
      Changes to <code class="literal">res:</code> databases are not persisted.</p>
<div class="section" title="Readonly Databases">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="mtc_readonly_database"></a>Readonly Databases</h4>
</div>
</div>
</div>
<p>A <em class="glossterm">file:</em> catalog can be made readonly
        permanently, or it can be opened as readonly. To make the database
        readonly, the property, value pair, <code class="literal">readonly=true</code>
        can be added to the <code class="filename">.properties</code> file of the
        database. The SHUTDOWN command must be used to close the database
        before making this change.</p>
<p>It is also possible to open a normal database as readonly. For
        this, the property can be included in the URL of the first connection
        to the database.</p>
<p>With readonly databases, it is still possible to insert and
        delete rows in TEMP tables.</p>
</div>
<div class="section" title="RES and Files Readonly Databases">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="N14401"></a>RES and Files Readonly Databases</h4>
</div>
</div>
</div>
<p>There is another option which allows MEMORY tables to be
        writeable, but without persisting the changes at SHUTDOWN. This option
        is activated with the property, value pair,
        <code class="literal">files_readonly=true</code>, which can be added to the
        <code class="filename">.properties</code> file of the database, or included in
        the URL of the first connection to the database.</p>
<p>A <em class="glossterm">res:</em> catalog, is a set of database
        files on the classpath (inside a jar or alongside class files). The
        database is opened with a URL in the form of
        <code class="literal">jdbc:hsqldb:res:&lt;database path&gt;</code>. These
        databases are always <code class="literal">files_readonly</code> and have the
        same restrictions as <code class="literal">files_readonly</code>
        <em class="glossterm">file:</em> catalogs.</p>
<p>CACHED tables and LOBS in these catalogs are readonly. It is not
        possible to create new LOBs in these catalogs, but you can use
        existing LOBs in new rows.</p>
<p>These options are useful for running application tests which
        operate on a predefined dataset.</p>
</div>
</div>
<div class="section" title="Tables">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="mtc_table_types"></a>Tables</h3>
</div>
</div>
</div>
<p>TEXT tables are designed for special applications where the data
      has to be in an interchangeable format, such as CSV (comma separated
      values). TEXT tables should not be used for routine storage of data that
      changes a lot.</p>
<p>MEMORY tables and CACHED tables are generally used for data
      storage. The difference between the two is as follows:</p>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>The data for all MEMORY tables is read from the *.script
            file when the database is started and stored in memory. In
            contrast the data for cached tables is not read into memory until
            the table is accessed. Furthermore, only part of the data for each
            CACHED table is held in memory, allowing tables with more data
            than can be held in memory.</p>
</li>
<li class="listitem">
<p>When the database is shutdown in the normal way, all the
            data for MEMORY tables is written out to the disk. In comparison,
            the data in CACHED tables that has changed is written out during
            operation and at shutdown.</p>
</li>
<li class="listitem">
<p>The size and capacity of the data cache for all the CACHED
            tables is configurable. This makes it possible to allow all the
            data in CACHED tables to be cached in memory. In this case, speed
            of access is good, but slightly slower than MEMORY tables.</p>
</li>
<li class="listitem">
<p>For normal applications it is recommended that MEMORY tables
            are used for small amounts of data, leaving CACHED tables for
            large data sets. For special applications in which speed is
            paramount and a large amount of free memory is available, MEMORY
            tables can be used for large tables as well.</p>
</li>
<li class="listitem">
<p>You can change the type of the table with the <code class="literal">SET
            TABLE &lt;table name&gt; TYPE { CACHED | MEMORY
            }</code>statement.</p>
</li>
</ul>
</div>
</div>
<div class="section" title="Large Objects">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="mtc_large_objects"></a>Large Objects</h3>
</div>
</div>
</div>
<p>HyperSQL 2.0 supports dedicated storage and access to BLOB and
      CLOB objects. These objects can have huge sizes. BLOB or CLOB is
      specified as the type of a column of the table. Afterwards, rows can be
      inserted into the table using a PreparedStatement for efficient transfer
      of large LOB data to the database. In <em class="glossterm">mem:</em>
      catalogs, CLOB and BLOB data is stored in memory. In
      <em class="glossterm">file:</em> catalogs, this data is stored in a single
      separate file which has the extension *.lobs. The size of this file can
      grow to huge, terabyte figures. By default, a minimum 32 KB is allocated
      to each LOB. You can reduced this if your LOBs are generally
      smaller.</p>
<p>LOB data should be stored in the database using a JDBC
      PreparedStatement object. The streaming methods send the LOB to the
      database in one operation as a binary or character stream. Inside the
      database, the disk space is allocated as needed and the data is saved as
      it is being received. LOB data should be retrieved from the database
      using a JDBC ResultSet method. When a streaming method is used to
      retrieve a LOB, it is retrieved in large chunks in a transparent manner.
      LOB data can also be retrieved as String or byte[], but these methods
      use more memory and may not be practical for large objects.</p>
<p>LOB data is not duplicated in the database when a lob is copied
      from one table to another. The disk space is reused when a LOB is
      deleted and is no longer contained in any table. This happens only at
      the time of a CHECKPOINT.</p>
<p>By using a dedicated LOB store, HyperSQL achieves consistently
      high speeds (usually over 20MB / s) for both storage and retrieval of
      LOBs.</p>
<p>There is an internal LOBS schema in the database to store the
      id's, sizes and addresses of the LOBs (but not the actual LOBS) in a few
      system tables. This schema is stored in the database as MEMORY tables.
      Therefore the amount of JVM memory should be increased when more than
      tens of thousands of LOBs are stored in the database. If your database
      contains more than a few hundreds of thousands of LOBs and memory use
      becomes an issue, you can change one or all LOB schema tables to CACHED
      tables. See statements below:</p>
<div class="example">
<a name="N14451"></a>
<p class="title">
<b>Example&nbsp;11.1.&nbsp;Using CACHED tables for the LOB schema</b>
</p>
<div class="example-contents">
<pre class="screen"> SET TABLE SYSTEM_LOBS.BLOCKS TYPE CACHED
 SET TABLE SYSTEM_LOBS.LOBS TYPE CACHED
 SET TABLE SYSTEM_LOBS.PARTS TYPE CACHED
 SET TABLE SYSTEM_LOBS.LOB_IDS TYPE CACHED
</pre>
</div>
</div>
<br class="example-break">
</div>
<div class="section" title="Deployment context">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="mtc_deploy_context"></a>Deployment context</h3>
</div>
</div>
</div>
<p>The files used for storing HyperSQL database data are all in the
      same directory. New files are always created and deleted by the database
      engine. Two simple principles must be observed:</p>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>The Java process running HyperSQL must have full privileges on
          the directory where the files are stored. This include create and
          delete privileges.</p>
</li>
<li class="listitem">
<p>The file system must have enough spare room both for the
          'permanent' and 'temporary' files. The default maximum size of the
          *.log file is 50MB. The *.data file can grow to up to 64GB (more if
          the default has been increased). The .backup file can be up to the
          size of the *.data file. The *.lobs file can grow to several
          terabytes. The temporary files created at the time of a SHUTDOWN can
          be equal in size to the *.script file and the .data file.</p>
</li>
<li class="listitem">
<p>In desktop deployments, virus checker programs may interfere
          with the creation and modification of database files. You should
          exclude the directory containing the database files from virus
          checking.</p>
</li>
</ul>
</div>
</div>
</div>
<div class="section" title="ACID, Persistence and Reliability">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="mtc_acid_persistence"></a>ACID, Persistence and Reliability</h2>
</div>
</div>
</div>
<p>HyperSQL 2.0 uses the same persistence mechanism as version 1.8, but
    with important enhancements. The code has proven reliable, as the last
    critical issue was fixed 2 years before the release of version 2.0.</p>
<p>There are further enhancements in version 2.2</p>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>More extensive locking mechanism has been added to code to
        support multithreaded access.</p>
</li>
<li class="listitem">
<p>Incremental backup (an internal mechanism for crash protection)
        allows fast checkpoint and shutdown.</p>
</li>
<li class="listitem">
<p>All files are synced at checkpoints and also just before
        closing.</p>
</li>
<li class="listitem">
<p>The data file is enlarged in block increments</p>
</li>
<li class="listitem">
<p>The NIO file access implementation has been improved</p>
</li>
</ul>
</div>
<p>Persistence relies on the JVM, the operating system, and the
    computer hardware. A database system like HSQLDB can perform millions of
    read and write operations in an hour. As system hardware and software can
    go wrong, it is impossible to achieve zero failure rate. Therefore regular
    backups are recommended. HyperSQL 2.2 has built-in database backup and
    restore features, discussed elsewhere in this chapter.</p>
<p>A note regarding the NIO file access implementation: This
    implementation applies only to CACHED table data in the
    <code class="literal">.data</code> file. Other files are not accessed via NIO. There
    has been an issue with some JVM implementations of nio not releasing the
    file buffers after they were closed. HyperSQL uses a workaround which is
    recommended for Sun JVM's. This does not apply to other JVM's. In such
    environments, it is therefore recommended to test the CHECKPOINT DEFRAG
    operation and the shutting down and restarting the database inside the
    same Java process extensively with NIO. Use of NIO can be turned off if
    necessary.</p>
<div class="section" title="Atomicity, Consistency, Isolation, Durability">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="mtc_acid"></a>Atomicity, Consistency, Isolation, Durability</h3>
</div>
</div>
</div>
<p>Atomicity means a transaction either fails without changing the
      data, or succeeds. HyperSQL ensures atomicity both during operations and
      in the event of a system crash.</p>
<p>Consistency means all the implicit and explicit integrity
      constraints are always enforced. HyperSQL always enforces the
      constraints and at the same time does not allow unenforceable
      constraints (illegal forms of CHECK constraints) to be created.</p>
<p>Isolation means transactions do not interfere with each other.
      HyperSQL enforces isolation according to strict rules of the database
      isolation model (MVCC or LOCKS).</p>
<p>Durability means a committed transaction is protected in case of a
      system crash. HyperSQL ensures durability according to the setting for
      WRITE DELAY MILLIS. A zero delay setting results in an
      FileDescriptor#sync() call each time a transaction commits. A timed
      delay means the FileDescriptor#sync() call is executed in the given
      intervals and only the last transactions committed in the time interval
      may be lost. The default time interval is 0.5 second. The sync() call is
      also made at all critical points, including when a file is about to be
      closed. Durability of files requires a reliable JVM and disk storage
      system that stores the data safely with a sync() call. In practice, many
      systems are generally reliable in this respect.</p>
</div>
<div class="section" title="System Operations">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="N14491"></a>System Operations</h3>
</div>
</div>
</div>
<p>A database is opened when the first connection is successfully
      made. It remains open until the <code class="literal">SHUTDOWN</code> command is
      issued. If the connection property shutdown=true is used for the first
      connection to the database, the database is shutdown when the last
      connection is closed. Otherwise the database remains open and will
      accept the next connection attempt.</p>
<p>The <code class="literal">SHUTDOWN</code> command shuts down the database
      properly and allows the database to be reopened quickly. This command
      may take some seconds as it saves all the modified data in the
      .<code class="literal">script</code> and <code class="literal">.data</code> files. Variants
      of <code class="literal">SHUTDOWN</code> such as <code class="literal">SHUTDOWN
      COMPACT</code> and <code class="literal">SHUTDOWN SCRIPT</code> can be used
      from time to time to reduce the overall size of the database files.
      Another variant is <code class="literal">SHUTDOWN IMMEDIATELY</code> which ensures
      all changes to data are stored in the <code class="literal">.log</code> file but
      does not save the changes in .<code class="literal">script</code> and
      <code class="literal">.data</code> files. The shutdown is performed quickly but
      the database will take much longer to reopen.</p>
<p>During the lifetime of the database the checkpoint operation may
      be performed from time to time. The <code class="literal">SET FILES LOG SIZE &lt;
      value &gt;</code> setting and its equivalent URL property determine
      the frequency of automatic checkpoints. An online backup also performs a
      checkpoint when the backup is not a hot backup. A checkpoint can be
      performed by the user at any time using the
      <code class="literal">CHECKPOINT</code> statement. The main purpose of checkpoints
      is to reduce the total size of database files and to allow a quick
      restart in case the database is closed without a proper shutdown. The
      <code class="literal">CHECKPOINT DEFRAG</code> variant compacts the
      <code class="literal">.data</code> file the same way as <code class="literal">SHUTDOWN
      COMPACT</code> does. Obviously this variant takes much longer than a
      normal <code class="literal">CHECKPOINT</code>. A database setting allows a
      <code class="literal">CHECKPOINT DEFRAG</code> to be performed automatically when
      wasted space in the <code class="literal">.data</code> file exceeds the specified
      percentage.</p>
<p>In a multi-user application, automatic or user-initiated
      checkpoints are delayed until all other sessions have committed or
      rolled back. During a checkpoint, other sessions cannot access the
      database tables but can access the <code class="literal">INFORMATION_SCHEMA</code>
      system tables.</p>
</div>
</div>
<div class="section" title="Backing Up Database Catalogs">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="mtc_backup"></a>Backing Up Database Catalogs</h2>
</div>
</div>
</div>
<a name="N144DC" class="indexterm"></a>
<p>The database engine saves the files containing all the data in a
    file catalog when a shutdown takes place. It automatically recovers from
    an abnormal termination and preserves the data when the catalog is opened
    next time. In an ideal operating environment, where there is no OS crash,
    disk failure, bugs in code, etc. there would be no need to backup a
    database. Backing up catalogs is an insurance policy against all sorts of
    misadventure that are not under the control of the database engine.</p>
<p>The data for each catalog consists of up to 5 files in the same
    directory with the endings such as <code class="literal">*.properties</code>,
    <code class="literal">*.script</code>, etc., as detailed in previous
    chapters.</p>
<p>HyperSQL 2 includes commands to backup the database files into a
    single <code class="literal">.tar</code> or <code class="literal">.tar.gz</code> file archive,
    or alternatively as copies of the database files. The backup can be
    performed by a command given in a JDBC session if the target database
    catalog is running, or on the command-line if the target catalog has been
    shutdown.</p>
<p>It is not recommended to backup the database file with an
    external file backup program while the database is running. The resulting
    backup will probably be inconsistent and not useful for restoring the
    database</p>
<div class="section" title="Making Online Backups">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="mtc_online_backup"></a>Making Online Backups</h3>
</div>
</div>
</div>
<p>To back up a running catalog, obtain a JDBC connection and
      issue a <code class="literal">BACKUP DATABASE</code> command in SQL. In its most
      simple form, the command format below will backup the database as a
      single <code class="literal">.tar.gz</code> file to the given directory. This type
      of backup performs a checkpoint immediately before backing up the
      files.</p>
<pre class="programlisting"> BACKUP DATABASE TO &lt;directory name&gt; BLOCKING [ AS FILES ]</pre>
<p>The <span class="emphasis"><em>directory name</em></span> must end with a slash
      to distinguish it as a directory, and the whole string must be in single
      quotes like so: <code class="literal">'subdir/nesteddir/'</code>.</p>
<p>Normal backup may take a long time with very large databases.
      Hot backup may be used in those situations. This type of backup does not
      perform a checkpoint and allows access to the database while backup is
      in progress.</p>
<pre class="programlisting"> BACKUP DATABASE TO &lt;directory name&gt; NOT BLOCKING [ AS FILES ]</pre>
<p>If you add AS FILES to the statements, the database files are
      backed up as separate files in the directory, without any gzip
      compression or tar archiving.</p>
<p>See the next section under Statements for details about the
      command and its options. See the sections below about restoring a
      backup.</p>
</div>
<div class="section" title="Making Offline Backups">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="mtc_offline_backup"></a>Making Offline Backups</h3>
</div>
</div>
</div>
<p>To back up an offline catalog, the catalog must be in shut down
      state. You will run a Java command like this. In this example, the
      database is named dbname and is in the dbdir directory. The backup is
      saved to a file named backup.tar in the tardir directory.</p>
<div class="example">
<a name="N14518"></a>
<p class="title">
<b>Example&nbsp;11.2.&nbsp;Offline Backup Example</b>
</p>
<div class="example-contents">
<pre class="screen"> java -cp hsqldb.jar org.hsqldb.lib.tar.DbBackupMain --save tardir/backup.tar dbdir/dbname</pre>
</div>
</div>
<p>
<br class="example-break">where <code class="filename">tardir/backup.tar</code> is a file path
      to the <code class="literal">*.tar</code> or <code class="literal">*.tar.gz</code> file to
      be created in your file system, and <code class="filename">dbdir/dbname</code> is
      the file path to the catalog file base name (in same fashion as in
      <code class="varname">server.database.*</code> settings and JDBC URLs with catalog
      type <em class="glossterm">file:</em>.</p>
</div>
<div class="section" title="Examining Backups">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="mtc_listing_backup"></a>Examining Backups</h3>
</div>
</div>
</div>
<p>You can list the contents of backup tar files with
      <code class="classname">DbBackup</code> on your operating system command line,
      or with any Pax-compliant tar or pax client (this includes GNU tar),
      </p>
<div class="example">
<a name="N14539"></a>
<p class="title">
<b>Example&nbsp;11.3.&nbsp;Listing a Backup with DbBackup</b>
</p>
<div class="example-contents">
<pre class="screen"> java -cp hsqldb.jar org.hsqldb.lib.tar.DbBackupMain --list tardir/backup.tar</pre>
</div>
</div>
<p>
<br class="example-break">You can also give regular expressions at the end of the
      command line if you are only interested in some of the file entries in
      the backup. Note that these are real regular expressions, not shell
      globbing patterns, so you would use <code class="literal">.+script</code> to match
      entries ending in "script", not <code class="literal">*script</code>.</p>
<p>You can examine the contents of the backup in their entirety by
      restoring the backup, as explained in the following section, to a
      temporary directory.</p>
</div>
<div class="section" title="Restoring a Backup">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="mtc_restoring_backup"></a>Restoring a Backup</h3>
</div>
</div>
</div>
<p>You use <code class="classname">DbBackup</code> on your operating system
      command line to restore a catalog from a backup. </p>
<div class="example">
<a name="N14550"></a>
<p class="title">
<b>Example&nbsp;11.4.&nbsp;Restoring a Backup with DbBackup</b>
</p>
<div class="example-contents">
<pre class="screen"> java -cp hsqldb.jar org.hsqldb.lib.tar.DbBackupMain --extract tardir/backup.tar dbdir</pre>
</div>
</div>
<p>
<br class="example-break">where <code class="filename">tardir/backup.tar</code> is a file path
      to the *.tar or *.tar.gz file to be read, and <code class="filename">dbdir</code>
      is the target directory to extract the catalog files into. Note that
      <code class="filename">dbdir</code> specifies a directory path, without the
      catalog file base name. The files will be created with the names stored
      in the tar file (and which you can see as described in the preceding
      section). After restoring the database, you can connect to it as
      usual.</p>
</div>
</div>
<div class="section" title="Encrypted Databases">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="mtc_encrypted_database"></a>Encrypted Databases</h2>
</div>
</div>
</div>
<p>HyperSQL supports encrypted databases. Encryption services use the
    Java Cryptography Extensions (JCE) and uses the ciphers installed with the
    JRE. HyperSQL itself does not contain any cryptography code.</p>
<p>Three elements are involved in specifying the encryption method and
    key. A cipher, together with its configuration is identified by a string
    which includes the name of the cipher and optional parameters. A provider
    is the fully qualified class name of the cipher provider. A key is
    represented as a hexadecimal string.</p>
<div class="section" title="Creating and Accessing an Encrypted Database">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="mtc_encrypted_create"></a>Creating and Accessing an Encrypted Database</h3>
</div>
</div>
</div>
<p>First, a key must be created for the desired cipher and
      configuration. This is done by calling the function CRYPT_KEY(&lt;cipher
      spec&gt;, &lt;provider&gt;). If the default provider (the built-in JVM
      ciphers) is used, then NULL should be specified as the provider. The
      CRYPT_KEY function returns a hexadecimal key. The function call can be
      made in any HyperSQL database, so long as the provider class is on the
      classpath. This key can be used to create a new encrypted database.
      Calls to this function always return different keys, based on a
      generated random values.</p>
<p>As an example, a call to CRYPT_KEY('Blowfish', null) returned the
      string, '604a6105889da65326bf35790a923932'. To create a new database,
      the URL below is used:</p>
<p>
<code class="literal">jdbc:hsqldb:file:&lt;database
      path&gt;;crypt_key=604a6105889da65326bf35790a923932;crypt_type=blowfish</code>
</p>
<p>The third property name is crypt_provider. This is specified only
      when the provider is not the default provider.</p>
<p>HyperSQL works with any symmetric cipher that may be available
      from the JVM.</p>
<p>The files that are encrypted include the .script, .data, .backup
      and .log files. The .lobs file is not encrypted by default. The property
      crypt_lobs=true must be specified to encrypt the .lobs file. When this
      property is used, the blobs and clobs are both compressed and
      encrypted.</p>
</div>
<div class="section" title="Speed Considerations">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="mtc_encrypted_speed"></a>Speed Considerations</h3>
</div>
</div>
</div>
<p>General operations on an encrypted database are performed the same
      as with any database. However, some operations are significantly slower
      than with the equivalent cleartext database. With MEMORY tables, there
      is no difference to the speed of SELECT statements, but data change
      statements are slower. With CACHED tables, the speed of all statements
      is slower.</p>
</div>
<div class="section" title="Security Considerations">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="mtc_encrypted_security"></a>Security Considerations</h3>
</div>
</div>
</div>
<p>Security considerations for encrypted databases have been
      discussed at length in HSQLDB discussion groups. Development team
      members have commented that encryption is not a panacea for all security
      needs. The following issues should be taken into account:</p>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>Encrypted files are relatively safe in transport, but
            because databases contain many repeated values and words,
            especially known tokens such as CREATE, INSERT, etc., breaking the
            encryption of a database may be simpler than an unknown
            file.</p>
</li>
<li class="listitem">
<p>Only the files are encrypted, not the memory image. Poking
            into computer memory, while the database is open, will expose the
            contents of the database.</p>
</li>
<li class="listitem">
<p>HyperSQL is open source. Someone who has the key, can
            compile and use a modified version of the program that saves a
            full cleartext dump of an encrypted database</p>
</li>
</ul>
</div>
<p>Therefore encryption is generally effective only when
      the users who have access to the crypt key are trusted.</p>
</div>
</div>
<div class="section" title="Monitoring Database Operations">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="mtc_monitoring_operation"></a>Monitoring Database Operations</h2>
</div>
</div>
</div>
<p>Database operations can be monitored at different levels using
    internal HyperSQL capabilities or add-ons.</p>
<div class="section" title="External Statement Level Monitoring">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="mtc_external_monitoring"></a>External Statement Level Monitoring</h3>
</div>
</div>
</div>
<p>Statement level monitoring allows you to gather statistics about
      executed statements. HyperSQL is supported by the monitoring tool JAMon
      (Java Application Monitor). JAMon is currently developed as the
      SourceForge project, jamonapi.</p>
<p>JAMon works at the JDBC level. It can monitor and gather
      statistics on different types of executed statements or other JDBC
      calls.</p>
<p>Early versions of JAMon were developed with HSQLDB and had to be
      integrated into HSQLDB at code level. The latest versions can be added
      on as a proxy in a much simpler fashion.</p>
</div>
<div class="section" title="Internal Statement Level Monitoring">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="mtc_internal_monitoring"></a>Internal Statement Level Monitoring</h3>
</div>
</div>
</div>
<p>The internally-generated, individual sql log for the database can
      be enabled with the <code class="literal">SET DATABASE EVENT LOG SQL LEVEL</code>
      statement, described in this chapter. As all the executed statements are
      logged, there is an impact on speed. So you should only use this for
      debugging. Two levels of sql logging are supported.</p>
</div>
<div class="section" title="Internal Event Monitoring">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="mtc_internal_event_monitoring"></a>Internal Event Monitoring</h3>
</div>
</div>
</div>
<p>HyperSQL can log important internal events of the engine. These
      events occur during the operation of the engine, and are not always
      coupled with the exact type of statement being executed. Normal events
      such as opening and closing of files, or errors such as OutOfMemory
      conditions are examples of logged events.</p>
<p>HyperSQL supports two methods of logging. One method is specific
      to the individual database and is managed internally by HyperSQL. The
      other method is specific to JVM and is managed by a logging
      framework.</p>
<p>The internally-generated, individual log for the database can be
      enabled with the <code class="literal">SET DATABASE EVENT LOG LEVEL</code>
      statement, described in this chapter. This method of logging is very
      useful for desktop application deployment, as it provides an ongoing
      record of database operations.</p>
</div>
<div class="section" title="Log4J and JDK logging">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="mtc_jdc_logging"></a>Log4J and JDK logging</h3>
</div>
</div>
</div>
<p>HyperSQL also supports log4J and JDK logging. The same event
      information that is passed to the internal log, is passed to external
      logging frameworks. These frameworks are typically configured outside
      HyperSQL. The log messages include the string "hsqldb.db." followed by
      the unique id (a 16 character string) of the database that generated the
      message, so they can be identified in a multi-database server
      context.</p>
<p>As the default JDK logging framework has several shortcomings,
      HyperSQL configures this logging framework for better operation. If you
      do not want HyperSQL to configure the JDK logging framework, you should
      include the system level property
      <code class="literal">hsqldb.reconfig_logging=false</code> in your
      environment.</p>
</div>
<div class="section" title="Server Operation Monitoring">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="mtc_server_monitoring"></a>Server Operation Monitoring</h3>
</div>
</div>
</div>
<p>A Server or WebServer instance can be started with the property
      server.silent=false. This causes all the connections and their executed
      statements to be printed to stdout as the statements are submitted to
      the server.</p>
</div>
</div>
<div class="section" title="Database Security">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="mtc_database_security"></a>Database Security</h2>
</div>
</div>
</div>
<p>HyperSQL has extensive security features which are implemented at
    different levels and covered in different chapters of this guide.</p>
<div class="orderedlist">
<ol class="orderedlist" type="1">
<li class="listitem">
<p>The server can use SSL and IP address access control lists. See
        the <a class="link" href="#listeners-chapt" title="Chapter&nbsp;13.&nbsp;HyperSQL Network Listeners (Servers)">HyperSQL Network Listeners
    (Servers)</a> chapter.</p>
</li>
<li class="listitem">
<p>You can define a system property to stop the database engine
        accessing the Java static functions that are on the classpath, apart
        from a limited set that you allow. See Securing Access to Classes in
        the <a class="link" href="#sqlroutines-chapt" title="Chapter&nbsp;8.&nbsp;SQL-Invoked Routines">SQL-Invoked Routines</a> chapter.</p>
</li>
<li class="listitem">
<p>You can define a system property to allow access to files on the
        file system outside the database directory and its children. This
        access is only necessary if you use TEXT tables. See the <a class="link" href="#texttables-chapt" title="Chapter&nbsp;5.&nbsp;Text Tables">Text Tables</a>
        chapter.</p>
</li>
<li class="listitem">
<p>The database files can be encrypted. Discussed in this
        chapter.</p>
</li>
<li class="listitem">
<p>Within the database, the DBA privileges are required for system
        and maintenance jobs.</p>
</li>
<li class="listitem">
<p>You can define users and roles and grant them access on
        different database objects. Each user has a password and is granted a
        set of privileges. See the <a class="link" href="#accesscontrol-chapt" title="Chapter&nbsp;6.&nbsp;Access Control">Access Control</a> chapter.</p>
</li>
<li class="listitem">
<p>You can define a password complexity check function for new and
        changed passwords. This is covered below under Authentication
        Settings.</p>
</li>
<li class="listitem">
<p>You can use external authentication instead of internally stored
        password to authenticate users for each database. This is covered
        below under Authentication Settings.</p>
</li>
</ol>
</div>
<p>HyperSQL security is multi-layered and avoids any loopholes to
    circumvent security. It is however the user's responsibility to enable the
    required level of security.</p>
<div class="section" title="Security Defaults">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="mtc_security_defaults"></a>Security Defaults</h3>
</div>
</div>
</div>
<p>The default setting are generally adequate for most embedded use
      of the database or for servers on the host that are accessed from the
      same machine. For servers accessed within a network, and especially for
      those accessed from outside the network, additional security settings
      must be used.</p>
<p>The default settings for server and web server do not use SSL or
      IP access control lists. These features are enabled programatically, or
      with the properties used to start the server.</p>
<p>The default settings allow a database user with the DBA role or
      with schema creation role to access static functions on the classpath.
      You can disable this feature or limit it to specific classes and
      methods. This can be done programatically or by setting a system
      property when you start a server.</p>
<p>If access to specific static functions is granted, then these
      functions must be considered as part of the database program and checked
      for any security flaws before inclusion in the classpath.</p>
<p>The default settings do not allow a user to access files outside
      the database directory. This access is for TEXT table source files. You
      can override this programatically or with a system property when you
      start a server.</p>
<p>The encryption of database file does not utilise any user-supplied
      information for encryption keys. This level of security is outside the
      realm of users and passwords.</p>
<p>The first user for a new database has the DBA role. This user name
      was always SA in older versions of HSQLDB, but not in the latest
      versions. The name of the first DBA user and its password can be
      specified when the database is created by the first connection to the
      database. These settings are then stored in the database.</p>
<p>The initial user with the DBA role should be used for admin
      purposes only. At least one additional role should be created for normal
      database use in the application and at least one additional user should
      be created and granted this role. The new role should not be given the
      DBA role. It can be given the CREATE_SCHEMA role, which allows it to
      create and access multiple schemas. Alternatively, the user with the DBA
      role can create the schemas and their objects and then grant specific
      privileges on the objects to the non-DBA role.</p>
</div>
<div class="section" title="Authentication Control">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="mtc_authentication_control"></a>Authentication Control</h3>
</div>
</div>
</div>
<p>Authentication is the mechanism that determines if a user can
      access the database at all. Once authentication is performed, the
      authorization mechanism is used to determine which database objects the
      particular user can access. The default authentication mechanism is
      password authentication. Each user is created with a password, which is
      stored in the database and checked each time a new database connection
      is created.</p>
<a name="N14612" class="indexterm"></a>
<p>
<span class="bold"><strong>Password Complexity
      Check</strong></span>
</p>
<p>HyperSQL allows you to define a function that checks the quality
      of the passwords defined in the database. The passwords are stored in
      the database. Each time a user connects, the user's name and password
      are checked against the stored list of users and passwords. The
      connection attempt is rejected if there is no match.</p>
<a name="N1461D" class="indexterm"></a>
<p>
<span class="bold"><strong>External
      Authentication</strong></span>
</p>
<p>You can use an external authentication mechanism instead of the
      internal authentication mechanism. HyperSQL allows you to define a
      function that checks the combination of database unique name, user name,
      and password for each connection attempt. The function can use external
      resources to authenticate the user. For example, a directory server may
      be used. The password may be ignored if the external resource can verify
      the user's credential without it.</p>
<p>You can override external authentication for a user with the ALTER
      USER statement. See the <a class="link" href="#accesscontrol-chapt" title="Chapter&nbsp;6.&nbsp;Access Control">Access Control</a> chapter</p>
</div>
</div>
<div class="section" title="Compatibility with Other RDBMS">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="mtc_compatibility_other"></a>Compatibility with Other RDBMS</h2>
</div>
</div>
</div>
<p>HyperSQL is used more than any other database engine for application
    testing and development targeted at other databases. Over the years, this
    usage resulted in developers finding and reporting many obscure bugs in
    HyperSQL, which have all been fixed in the latest version. Also, HyperSQL
    2 has been written to the SQL Standard and avoids the traps caused by
    superficial imitation of existing RDBMS.</p>
<p>HyperSQL has many property settings that relax conformance to the
    Standard in order to allow compatibility with other RDBMS, without
    breaking the core integrity of the database. These properties are modified
    with SET DATABASE SQL statements described in the SQL Conformance Settings
    section of this chapter</p>
<p>The SQL Standard has existed since 1989 and has been expanded over
    the years in several revisions. Also, the X-Open specification has defined
    a number of SQL functions which are implemented by most RDBMS.</p>
<p>Each RDBMS supports additional functions that are not covered by the
    standard. Some RDBMS use non-standard syntax for some operations.
    Fortunately, most popular RDBMS products have introduced better
    compatibility with the Standard in their recent versions, but there are
    still some portability issues. HyperSQL overcomes the potability issues
    using these strategies</p>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>An extensive set of functions cover the SQL Standard, X-Open,
        and most of the useful functions that other RDBMS may support.</p>
</li>
<li class="listitem">
<p>Database properties, which can be specified on the URL or as SQL
        statements, relax conformance to the Standard in order to allow
        non-standard comparisons and assignments allowed by other
        RDBMS.</p>
</li>
<li class="listitem">
<p>Specific SQL syntax compatibility modes allow syntax and type
        names that are supported by some popular RDBMS.</p>
</li>
<li class="listitem">
<p>User-defined types and functions, including aggregate functions,
        allow any type or function that is supported by some RDBMS to be
        defined and used.</p>
</li>
</ul>
</div>
<p>In the future, the supported compatibility modes with other RDBMS
    will be expanded further.</p>
<div class="section" title="PostgreSQL Compatibility">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="mtc_compatibility_postgres"></a>PostgreSQL Compatibility</h3>
</div>
</div>
</div>
<p>PostgreSQL is fairly compatible with the Standard, but uses some
      non-standard features.</p>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>Use <code class="literal">&lt;set database sql syntax PGS
          statement&gt;</code> to enable the PostgreSQL's non-standard
          features. References to SERIAL, BIGSERIAL and TEXT data types, as
          well as sequence functions, are translated into HSQLDB
          equivalents.</p>
</li>
<li class="listitem">
<p>Use MVCC if your application is multi-user</p>
</li>
<li class="listitem">
<p>PostgreSQL functions are generally supported</p>
</li>
<li class="listitem">
<p>For identity columns, PostgreSQL uses a non-standard linkage
          with an external identity sequence. In most cases, this can be
          converted to <code class="literal">GENERATED BY DEFAULT AS IDENTITY</code>. In
          those cases where the identity sequence needs to be shared by
          multiple tables, you can use a new HyperSQL 2.2 feature
          <code class="literal">GENERATED BY DEFAULT AS SEQUENCE &lt;sequence
          name&gt;</code>, which is the equivalent of the PostgreSQL
          implementation.</p>
</li>
<li class="listitem">
<p>In CREATE TABLE statements, the SERIAL and BIGSERIAL types are
          translated into INTEGER or BIGINT, with <code class="literal">GENERATED BY
          DEFAULT AS IDENTITY</code>. Usage of DEFAULT NEXTVAL(&lt;sequence
          name&gt;) is supported so long as the <code class="literal">&lt;sequence
          name&gt;</code> refers to an existing sequence. This usage is
          translated into <code class="literal">GENERATED BY DEFAULT AS SEQUENCE
          &lt;sequence name&gt;</code>.</p>
</li>
<li class="listitem">
<p>In SELECT and other statements, the
          <code class="literal">NEXTVAL(&lt;sequence name&gt;)</code> and
          <code class="literal">LASTVAL()</code> functions are supported and translated
          into HyperSQL's <code class="literal">NEXT VALUE FOR &lt;sequence
          name&gt;</code> and <code class="literal">IDENTITY()</code>
          expressions.</p>
</li>
<li class="listitem">
<p>PostgreSQL uses a non-standard expression, <code class="literal">SELECT 'A
          Test String'</code> to return a single row table. The standard
          form is <code class="literal">VALUES('A Test String')</code>. In PGS syntax
          mode, this type of SELECT is supported.</p>
</li>
<li class="listitem">
<p>HyperSQL supports SQL Standard ARRAY types. PostgreSQL also
          supports this, but not entirely according to the Standard.</p>
</li>
<li class="listitem">
<p>SQL routines are portable, but some syntax elements are
          different and require changes.</p>
</li>
<li class="listitem">
<p>You may need to use <code class="literal">SET DATABASE SQL TDC { DELETE |
          UPDATE } FALSE</code> statements, as PostgreSQL does not enforce
          the subtle rules of the Standard for foreign key cascading deletes
          and updates.</p>
</li>
</ul>
</div>
</div>
<div class="section" title="MySQL Compatibility">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="mtc_compatibility_mysql"></a>MySQL Compatibility</h3>
</div>
</div>
</div>
<p>MySQL had many incompatibilities with the Standard. The latest
      versions have introduced much greater compatibly, but some of these
      features have to be turned on via properties. You should therefore check
      the current Standard compatibility settings of your MySQL database and
      use the available HyperSQL properties to achieve closer results. If you
      avoid the few anti-Standard features of MySQL you can port your
      databases to HyperSQL.</p>
<p>HyperSQL does not have the following non-standard limitations of
      MySQL.</p>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>With HyperSQL, an UPDATE statement can update UNIQUE and
          PRIMARY KEY columns of a table without causing an exception due to
          temporary violation of constraints. These constraints are checked at
          the end of execution, therefore there is no need for an ORDER BY
          clause in an UPDATE statement.</p>
</li>
<li class="listitem">
<p>MySQL foreign key constraints are not enforced by the default
          MyISAM engine. Be aware of the possibility of data being rejected by
          HyperSQL due to these constraints.</p>
</li>
<li class="listitem">
<p>With HyperSQL INSERT or UPDATE statements either succeed or
          fail due to constraint violation. MySQL has the non-standard IGNORE
          overrides to ignore violations, which is not accepted by
          HyperSQL.</p>
</li>
<li class="listitem">
<p>Unlike MySQL, HyperSQL allows you to modify a table with an
          INSERT, UPDATE or DELETE statement which selects from the same table
          in a subquery.</p>
</li>
</ul>
</div>
<p>Follow the guidelines below for converting MySQL databases and
      applications.</p>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>Use <code class="literal">&lt;set database sql syntax MYS
          statement&gt;</code> to enable support for AUTO_INCREMENT and
          TEXT data types. These type definitions are translated into HSQLDB
          equivalents.</p>
</li>
<li class="listitem">
<p>Use MVCC with <code class="literal">&lt;set database transaction control
          statement&gt;</code> if your application is multi-user.</p>
</li>
<li class="listitem">
<p>Avoid storing invalid values, for example invalid dates such
          as '0000-00-00' or '2001-00-00' which are rejected by
          HyperSQL.</p>
</li>
<li class="listitem">
<p>Avoid the MySQL feature that trims spaces at the end of CHAR
          values.</p>
</li>
<li class="listitem">
<p>In MySQL, a database is the same as a schema. In HyperSQL
          several schemas can exist in the same database and accessed
          transparently. In addition a HyperSQL server supports multiple
          separate databases.</p>
</li>
<li class="listitem">
<p>In MySQL, older, non-standard, forms of database object name
          case-sensitivity make is difficult to port applications. Use the
          latest form which encloses case-sensitive names in double
          quotes.</p>
</li>
<li class="listitem">
<p>MySQL functions are generally supported, including
          GROUP_CONCAT.</p>
</li>
<li class="listitem">
<p>For fine control over type conversion, check the settings for
          <code class="literal">&lt;set database sql convert truncate
          statement&gt;</code>
</p>
</li>
<li class="listitem">
<p>If you use concatenation of possibly NULL values in your
          select statements, you may need to change the setting with the
          <code class="literal">&lt;set database sql concat nulls
          statement&gt;</code>
</p>
</li>
<li class="listitem">
<p>MySQL supports most SQL Standard types (except INTERVAL
          types), as well as non-standard types, which are also supported by
          HyperSQL. Supported types include SMALLINT, INT, BIGINT, DOUBLE,
          FLOAT, DECIMAL, NUMERIC, VARCHAR, CHAR, BINARY, VARBINARY, BLOB,
          DATE, TIMESTAMP (all Standard SQL) and TINYINT, DATETIME (non
          Standard).</p>
</li>
<li class="listitem">
<p>MySQL uses a non-standard expression, <code class="literal">SELECT 'A Test
          String'</code> to return a single row table. The standard form is
          <code class="literal">VALUES('A Test String')</code>. In MYS syntax mode, this
          type of SELECT is supported.</p>
</li>
<li class="listitem">
<p>SQL user-defined function and procedure syntax is very similar
          to SQL Standard syntax. A few changes may still be required.</p>
</li>
</ul>
</div>
</div>
<div class="section" title="Firebird Compatibility">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="mtc_compatibility_firebird"></a>Firebird Compatibility</h3>
</div>
</div>
</div>
<p>Firebird generally follows the SQL Standard. Applications can be
      ported to HyperSQL without difficulty.</p>
</div>
<div class="section" title="Apache Derby Compatibility">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="mtc_compatibility_derby"></a>Apache Derby Compatibility</h3>
</div>
</div>
</div>
<p>Apache Derby supports a smaller subset of the SQL Standard
      compared to HyperSQL. Applications can be ported to HyperSQL without
      difficulty.</p>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>Use MVCC with <code class="literal">&lt;set database transaction control
          statement&gt;</code> if your application is multi-user.</p>
</li>
<li class="listitem">
<p>HyperSQL supports Java language functions and stored
          procedures with the standard syntax, which is similar to the way
          Derby supports these features.</p>
</li>
</ul>
</div>
</div>
<div class="section" title="Oracle Compatibility">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="mtc_compatibility_oracle"></a>Oracle Compatibility</h3>
</div>
</div>
</div>
<p>Recent versions of Oracle support Standard SQL syntax for outer
      joins and many other operations. In addition, HyperSQL features a
      setting to support Oracle syntax and semantics for the most widely used
      non-standard features.</p>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>Use <code class="literal">&lt;set database sql syntax ORA
          statement&gt;</code> to enable support for some non-standard
          syntax of Oracle.</p>
</li>
<li class="listitem">
<p>Use MVCC with <code class="literal">&lt;set database transaction control
          statement&gt;</code> if your application is multi-user.</p>
</li>
<li class="listitem">
<p>Fine control over MVCC deadlock avoidance is provided by the
          <code class="literal">&lt;set database transaction rollback on conflict
          statement&gt;</code> and the corresponding
          <code class="literal">hsqldb.tx_conflict_rollback</code> connection
          property.</p>
</li>
<li class="listitem">
<p>If your application relies on Oracle behaviour for nulls in
          multi-column UNIQUE constraints, use <code class="literal">&lt;set database sql
          unique nulls statement&gt;</code> to change the default.</p>
</li>
<li class="listitem">
<p>If your application relies on Oracle behaviour for ordering of
          nulls in SELECT statements with ORDER BY, but without NULLS FIRST or
          NULLS LAST, use both <code class="literal">&lt;set database sql nulls last
          statement&gt;</code> and <code class="literal">&lt;set database sql nulls
          order statement&gt;</code> to change the defaults.</p>
</li>
<li class="listitem">
<p>If you use the non-standard concatenation of possibly NULL
          values in your select statements, you may need to change the setting
          for <code class="literal">&lt;set database sql concat nulls
          statement&gt;</code>.</p>
</li>
<li class="listitem">
<p>Many Oracle functions are supported, including no-arg
          functions such as SYSDATE and SYSTIMESTAMP and more complex ones
          such as TO_DATE and TO_CHAR.</p>
</li>
<li class="listitem">
<p>Non-standard data type definitions such as NUMBER, VARCHAR2,
          NVARCHAR2, BINARY_DOUBLE, BINARY_FLOAT, LONG, RAW are translated
          into the closest HyperSQL / SQL Standard equivalent in ORA
          mode.</p>
</li>
<li class="listitem">
<p>The DATE type is interpreted as TIMESTAMP(0) in ORA syntax
          mode.</p>
</li>
<li class="listitem">
<p>The DUAL table and the expressions, ROWNUM, CURRVAL, NEXTVAL
          are supported in ORA syntax mode.</p>
</li>
<li class="listitem">
<p>HyperSQL natively supports operations involving datetime and
          interval values. These features are based on the SQL
          Standard.</p>
</li>
<li class="listitem">
<p>Many subtle automatic type conversions, syntax refinements and
          other common features are supported.</p>
</li>
<li class="listitem">
<p>SQL routines are generally portable, but some changes may be
          required.</p>
</li>
</ul>
</div>
</div>
<div class="section" title="DB2 Compatibility">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="mtc_compatibility_db2"></a>DB2 Compatibility</h3>
</div>
</div>
</div>
<p>DB2 is highly compatible with the SQL Standard (except its lack of
      support for the INFORMATION_SCHEMA). Applications can be ported to
      HyperSQL without difficulty.</p>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>Use <code class="literal">&lt;set database sql syntax DB2
          statement&gt;</code> to enable support for some non-standard
          syntax of DB2.</p>
</li>
<li class="listitem">
<p>Use MVCC with <code class="literal">&lt;set database transaction control
          statement&gt;</code> if your application is multi-user.</p>
</li>
<li class="listitem">
<p>HyperSQL supports almost the entire syntax of DB2 together
          with many of the functions. Even local temporary tables using the
          SESSION pseudo schema are supported.</p>
</li>
<li class="listitem">
<p>The DB2 binary type definition FOR BIT DATA, as well as empty
          definition of column default values are supported in DB2 syntax
          mode.</p>
</li>
<li class="listitem">
<p>Many DB2 functions are supported.</p>
</li>
<li class="listitem">
<p>The DUAL table and the expressions, ROWNUM, CURRVAL, NEXTVAL
          are supported in DB2 syntax mode.</p>
</li>
<li class="listitem">
<p>SQL routines are highly portable with minimal change.</p>
</li>
</ul>
</div>
</div>
<div class="section" title="MS SQLServer and Sybase Compatibility">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="mtc_compatibility_mssql"></a>MS SQLServer and Sybase Compatibility</h3>
</div>
</div>
</div>
<p>SQLServer has some incompatibilities with the Standard syntax. The
      most significant is the use of square brackets instead of double quotes
      for case-sensitive column names.</p>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>Use <code class="literal">&lt;set database sql syntax MSS
          statement&gt;</code> to enable support for the
          <code class="literal">CONVERT(&lt;type definition&gt;, &lt;expression)</code>
          function with switched order of arguments</p>
</li>
<li class="listitem">
<p>Use MVCC with <code class="literal">&lt;set database transaction control
          statement&gt;</code> if your application is multi-user.</p>
</li>
<li class="listitem">
<p>If you use the non-standard concatenation of possibly NULL
          values in your select statements, you may need to change the setting
          for &lt;set database sql concat nulls statement&gt;.</p>
</li>
<li class="listitem">
<p>HyperSQL supports + for string concatenation. It also supports
          many functions supported by these dialects.</p>
</li>
<li class="listitem">
<p>SQLServer uses a non-standard expression, <code class="literal">SELECT 'A
          Test String'</code> to return a single row table. The standard
          form is <code class="literal">VALUES('A Test String')</code>. In MSS syntax
          mode, this type of SELECT is supported.</p>
</li>
<li class="listitem">
<p>SQL routines need quite a lot of changes.</p>
</li>
</ul>
</div>
</div>
</div>
<div class="section" title="Statements">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="mtc_statements"></a>Statements</h2>
</div>
</div>
</div>
<p>System level statements are listed in this section. Statements that
    begin with SET DATABASE or SET FILES are for properties that have an
    effect on the normal operation of HyperSQL. The effects of these
    statements are also discussed in different chapters.</p>
<div class="section" title="System Operations">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="mtc_system_operations"></a>System Operations</h3>
</div>
</div>
</div>
<p>These statements perform a system level action.</p>
<a name="N14793" class="indexterm"></a>
<p>
<span class="bold"><strong>SHUTDOWN</strong></span>
</p>
<p>
<span class="emphasis"><em>shutdown statement</em></span>
</p>
<p>
<code class="literal">&lt;shutdown statement&gt; ::= SHUTDOWN [IMMEDIATELY |
      COMPACT | SCRIPT]</code>
</p>
<p>Shutdown the database. If the optional qualifier is not used, a
      normal SHUTDOWN is performed. A normal SHUTDOWN ensures all data is
      saved correctly and the database opens without delay on next
      use.</p>
<div class="variablelist">
<table border="0">
<col valign="top" align="left">
<tbody>
<tr>
<td>
<p>
<span class="term">SHUTDOWN</span>
</p>
</td><td>
<p>Normal shutdown saves all the database files, then deletes
            the .log file (and the .backup file in the default mode). This
            does the same thing as CHECKPOINT, but closes the database when it
            completes. The database opens without delay on next used.</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="term">SHUTDOWN IMMEDIATELY</span>
</p>
</td><td>
<p>Saves the *.log file and closes the database files. This is
            the quickest form of shutdown. This command should not be used as
            the routine method of closing the database, because when the
            database is accessed next time, it may take a long time to
            start.</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="term">SHUTDOWN COMPACT</span>
</p>
</td><td>
<p>This is similar to normal SHUTDOWN, but reduces the *.data
            file to its minimum size. It can take much longer than normal
            SHUTDOWN. This shouldn't be used as routine.</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="term">SHUTDOWN SCRIPT</span>
</p>
</td><td>
<p>This is similar to SHUTDOWN COMPACT, but it does not rewrite
            the <code class="literal">*.data</code> and text table files. After SHUTDOWN
            SCRIPT, only the <code class="literal">*.script</code> and
            <code class="literal">*.properties</code> files remain. At the next startup,
            these files are processed and the <code class="literal">*.data</code> file
            is created if there are cached tables. This command in effect
            performs part of the job of SHUTDOWN COMPACT, leaving the other
            part to be performed automatically at the next startup.</p>
<p>This command produces a full script of the database which
            can be edited for special purposes prior to the next
            startup.</p>
</td>
</tr>
</tbody>
</table>
</div>
<p>Only a user with the DBA role can execute this
      statement.</p>
<a name="N147CD" class="indexterm"></a>
<p>
<span class="bold"><strong>BACKUP DATABASE</strong></span>
</p>
<p>
<span class="emphasis"><em>backup database statement</em></span>
</p>
<p>
<code class="literal">&lt;backup database statement&gt; ::= BACKUP DATABASE
      TO &lt;file path&gt; [SCRIPT] {[NOT] COMPRESSED} {[NOT] BLOCKING} [AS
      FILES]</code>
</p>
<p>Backup the database to specified <code class="literal">&lt;file
      path&gt;</code> for archiving purposes.</p>
<p>The <code class="literal">&lt;file path&gt;</code> can be in two forms.
      If the <code class="literal">&lt;file path&gt;</code> ends with a forward slash,
      it specifies a directory. In this case, an automatic name for the
      archive is generated that includes the date, time and the base name of
      the database. The database is backed up to this archive file in the
      specified directory. The archive is in <code class="literal">.tar.gz</code> or
      <code class="literal">.tar</code> format depending on whether it is compressed or
      not.</p>
<p>If the <code class="literal">&lt;file path&gt;</code> does not end with a
      forward slash, it specifies a user-defined file name for the backup
      archive. The file extension must be either <code class="literal">.tar.gz</code> or
      <code class="literal">.tar</code> and this must match the compression
      option.</p>
<p>The default set of options is COMPRESSED BLOCKING.</p>
<p>If SCRIPT is specified, the backup will contain a
      <code class="literal">*.script</code> file, which contain all the data and
      settings of the database. This type of backup is suitable for smaller
      databases. With larger databases, this takes a long time. When the
      SCRIPT option is no used, the backup set will consist of the current
      snapshot of all database files.</p>
<p>If NOT COMPRESSED is specified, the backup is a tar file,
      without compression. Otherwise, it is in gzip format.</p>
<p>The qualifier, BLOCKING, means all database operations are
      suspended during backup. During backup, a CHECKPOINT command is silently
      executed. This mode is always used when SCRIPT is specified.</p>
<p>Hot backup is performed if NOT BLOCKING is specified. In this
      mode, the database can be used during backup. This mode should only be
      used with very large databases. A hot backup set is less compact and
      takes longer to restore and use than a normal backup set produced with
      the BLOCKING option. You can perform a CHECKPOINT just before a hot
      backup in order to reduce the size of the backup set.</p>
<p>If AS FILES is specified, the database files are copied to a
      directory specified by &lt;file path&gt; without any compression. The
      file path must be a directory. If the directory does not exist, it is
      created. The file path may be absolute or relative. If it is relative,
      it is interpreted as relative to the location of database files. When AS
      FILES is specified, SCRIPT or COMPRESSED options are not available. The
      backup can be performed as BLOCKING or NOT BLOCKING.</p>
<p>The HyperSQL jar also contains a program that creates an
      archive of an offline database. It also contains a program to expand an
      archive into database files. These programs are documented in this
      chapter under Backing up Database Catalogs.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<a name="N1480D" class="indexterm"></a>
<p>
<span class="bold"><strong>CHECKPOINT</strong></span>
</p>
<p>
<span class="emphasis"><em>checkpoint statement</em></span>
</p>
<p>
<code class="literal">&lt;checkpoint statement&gt; ::= CHECKPOINT
      [DEFRAG]</code>
</p>
<p>Closes the database files, rewrites the script file, deletes
      the log file and reopens the database.</p>
<p>If <code class="literal">DEFRAG</code> is specified, also shrinks the
      <code class="literal">*.data</code> file to its minimum size. <code class="literal">CHECKPOINT
      DEFRAG</code> time depends on the size of the database and can take a
      long time with huge databases.</p>
<p>A checkpoint on a multi-user database waits until all other
      sessions have committed or rolled back. While the checkpoint is in
      progress other sessions are kept waiting. Checkpoint does not close any
      sessions.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<a name="N1482D" class="indexterm"></a>
<p>
<span class="bold"><strong>SCRIPT</strong></span>
</p>
<p>
<span class="emphasis"><em>script statement</em></span>
</p>
<p>
<code class="literal">&lt;script statement&gt; ::= SCRIPT [&lt;file
      name&gt;]</code>
</p>
<p>Returns a script containing SQL statements that define the
      database, its users, and its schema objects. If <code class="literal">&lt;file
      name&gt;</code> is not specified, the statements are returned in a
      ResultSet, with each row containing an SQL statement. No data statements
      are included in this form. The optional file name is a single-quoted
      string. If <code class="literal">&lt;file name&gt;</code> is specified, then the
      script is written to the named file. In this case, all the data in all
      tables of the database is included in the script as INSERT
      statements.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
</div>
<div class="section" title="Database Settings">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="mtc_database_settings"></a>Database Settings</h3>
</div>
</div>
</div>
<p>These statements change the database settings.</p>
<a name="N1484C" class="indexterm"></a>
<p>
<span class="bold"><strong>SET DATABASE
      COLLATION</strong></span>
</p>
<p>
<span class="emphasis"><em>set database collation statement</em></span>
</p>
<p>
<code class="literal">&lt;set database collation statement&gt; ::= SET
      DATABASE COLLATION &lt;collation name&gt; [ NO PAD | PAD SPACE
      ]</code>
</p>
<p>Each database can have its own default collation. Sets the
      collation from the set of collations supported by HyperSQL. Once this
      command has been issued, the database can be opened in any JVM and will
      retain its collation.</p>
<p>All collations pad the shorter string with spaces when two
      strings are compared. If NO PAD is specified, comparison is performed
      without padding. The default system collation is named
      <code class="literal">SQL_TEXT</code>. To use the default without padding use
      <code class="literal">SET DATABASE COLLATION SQL_TEXT NO PAD</code>.</p>
<p>After you change the collation for a database that contains
      collated data, you must execute <code class="literal">SHUTDOWN COMPACT</code> or
      <code class="literal">SHUTDOWN SCRIPT</code> in order to recreate the
      indexes.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>Collations are discussed in the <a class="link" href="#databaseobjects-chapt" title="Chapter&nbsp;4.&nbsp;Schemas and Database Objects">Schemas and Database Objects</a> chapter. Some examples of
      setting the database collation follow:</p>
<pre class="programlisting"> -- this collation is an ascii collation with Upper Case Comparison (coverts strings to uppercase for comparison)
 SET DATABASE COLLATION SQL_TEXT_UCC

 -- this collation is case-insensitive English
 SET DATABASE COLLATION "English 1"
 -- this collation is case-sensitive French
 SET DATABASE COLLATION "French 2"  </pre>
<a name="N14878" class="indexterm"></a>
<p>
<span class="bold"><strong>SET DATABASE DEFAULT RESULT MEMORY
      ROWS</strong></span>
</p>
<p>
<span class="emphasis"><em>set database default result memory rows
      statement</em></span><code class="literal"> </code>
</p>
<p>
<code class="literal">&lt;set database default result memory rows&gt; ::=
      SET DATABASE DEFAULT RESULT MEMORY ROWS &lt;unsigned integer
      literal&gt;</code>
</p>
<p>Sets the maximum number of rows of each result set and internal
      temporary table that is held in memory. Temporary tables includes views,
      schema-based and session-based TEMPORARY tables, transient tables for
      subqueries, and <code class="literal">INFORMATION_SCHEMA</code> tables.</p>
<p>This setting applies to all sessions. Individual sessions can
      change the value with the <code class="literal">SET SESSION RESULT MEMORY
      ROWS</code> statement. The default is 0, meaning all result sets are
      held in memory.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>This is equivalent to the connection property
      <code class="literal">hsqldb.result_max_memory_rows</code>.</p>
<a name="N1489A" class="indexterm"></a>
<p>
<span class="bold"><strong>SET DATABASE DEFAULT TABLE
      TYPE</strong></span>
</p>
<p>
<span class="emphasis"><em>set database default table type
      statement</em></span><code class="literal"> </code>
</p>
<p>
<code class="literal">&lt;set database default table type&gt; ::= SET
      DATABASE DEFAULT TABLE TYPE { CACHED | MEMORY }</code>
</p>
<p>Sets the type of table created when the next CREATE TABLE
      statement is executed. The default is MEMORY.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>This is equivalent to the connection property
      <code class="literal">hsqldb.default_table_type</code>.</p>
<a name="N148B4" class="indexterm"></a>
<p>
<span class="bold"><strong>SET DATABASE EVENT LOG
      LEVEL</strong></span>
</p>
<p>
<span class="emphasis"><em>set database event log level
      statement</em></span>
</p>
<p>
<code class="literal">&lt;set database event log level&gt; ::= SET DATABASE
      EVENT LOG [ SQL ] LEVEL { 0 | 1 | 2 | 3 }</code>
</p>
<p>When the SQL option is not used, this statement sets the amount
      of information logged in the internal, database-specific event log.
      Level 0 means no log. Level 1 means only important (error) events. Level
      2 means more events, including both important and less important
      (normal) events. Level 3 includes even more details. For readonly and
      <em class="glossterm">mem:</em> databases, if the level is set above 0, the
      log messages are directed to stderr.</p>
<p>The events are logged in a file with the extension
      <code class="literal">.app.log</code> alongside the main database files.</p>
<p>This is equivalent to the connection property
      <code class="literal">hsqldb.applog</code>.</p>
<p>When the SQL option is used, this statement logs the SQL
      statements as they are executed. Each log line contains the timestamp
      and the session number, followed by the SQL statement and JDBC arguments
      if any.</p>
<p>Levels 1, 2 and 3 are supported. Level 1 only logs commits and
      rollbacks, while Level 2 and 3 log all statements. Level 2 truncates
      long statements, while level 3 reports the full statement and parameter
      values.</p>
<p>The logged lines are stored in a file with the extension
      <code class="literal">.sql.log</code> alongside the main database files.</p>
<p>This is equivalent to the connection property
      <code class="literal">hsqldb.sqllog</code>.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>In version 2.3, the equivalent URL properties,
      <code class="literal">hsqldb.app_log</code> and <code class="literal">hsqldb.sql_log</code>,
      can be used not only for a new database, but also when opening an
      existing file database to change the event log level.</p>
<p>An extract from an .sql.log file created with log Level 3 is
      shown below. The numbers after the timestamp (10 and 1) show the session
      number. The values for prepared statement parameters are shown in
      parentheses at the end of the statement.</p>
<div class="example">
<a name="N148EC"></a>
<p class="title">
<b>Example&nbsp;11.5.&nbsp;SQL Log Example</b>
</p>
<div class="example-contents">
<pre class="screen"> 2012-11-29 10:40:40.250 10 INSERT INTO TEST_CLOB VALUES (1,'Ut wisi enim ad minim veniam, quis nostrud exerci') 
 2012-11-29 10:40:40.250 1 INSERT INTO SYSTEM_LOBS.LOB_IDS VALUES(?, ?, ?, ?) (1,49,0,40)
 2012-11-29 10:40:40.250 1 COMMIT 
 2012-11-29 10:40:40.265 1 CALL SYSTEM_LOBS.ALLOC_BLOCKS(?, ?, ?) (1,0,1)
 2012-11-29 10:40:40.265 1 COMMIT 
</pre>
</div>
</div>
<br class="example-break">
<a name="N148F1" class="indexterm"></a>
<p>
<span class="bold"><strong>SET DATABASE GC</strong></span>
</p>
<p>
<span class="emphasis"><em>set database gc statement</em></span>
</p>
<p>
<code class="literal">&lt;set database gc statement&gt; ::= SET DATABASE GC
      &lt;unsigned integer literal&gt;</code>
</p>
<p>An optional property which forces calls to <code class="literal">System.gc()
      </code>after the specified number of row operations. The default
      value for this property is 0, which means no System.gc() calls. Usual
      values for this property range from 10000 depending on the system and
      the memory allocation. This property may be useful in some in-process
      deployments, especially with older JVM implementations.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<a name="N14907" class="indexterm"></a>
<p>
<span class="bold"><strong>SET DATABASE UNIQUE
      NAME</strong></span>
</p>
<p>
<span class="emphasis"><em>set database unique name</em></span><code class="literal">
      </code>
</p>
<p>
<code class="literal">&lt;set database unique name statement&gt; ::= SET
      DATABASE UNIQUE NAME &lt;identifier&gt;</code>
</p>
<p>Each HyperSQL catalog (database) has an engine-generated
      internal name. This name is a 16 character long string, beginning with
      HSQLDB and based on the time of creation of the database. The name is
      used for the log events that are sent to external logging frameworks.
      The new name must be exactly 16 characters long with no
      spaces.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<a name="N1491C" class="indexterm"></a>
<p>
<span class="bold"><strong>SET DATABASE TRANSACTION
      CONTROL</strong></span>
</p>
<p>
<span class="emphasis"><em>set database transaction control
      statement</em></span>
</p>
<p>
<code class="literal">&lt;set database transaction control statement&gt; ::=
      SET DATABASE TRANSACTION CONTROL { LOCKS | MVLOCKS | MVCC
      }</code>
</p>
<p>Set the concurrency control system for the database. It can be
      issued only when all sessions have been committed or rolled back. This
      command and its modes is discussed in the <a class="link" href="#sessions-chapt" title="Chapter&nbsp;3.&nbsp;Sessions and Transactions">Sessions and Transactions</a> chapter.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>This is equivalent to the connection property
      <code class="literal">hsqldb.tx</code>.</p>
<a name="N14938" class="indexterm"></a>
<p>
<span class="bold"><strong>SET DATABASE TRANSACTION ROLLBACK ON
      CONFLICT</strong></span>
</p>
<p>
<span class="emphasis"><em>set database transaction rollback on conflict
      statement</em></span>
</p>
<p>
<code class="literal">&lt;set database transaction rollback on conflict
      statement&gt; ::= SET DATABASE TRANSACTION ROLLBACK ON CONFLICT { TRUE |
      FALSE }</code>
</p>
<p>When a transaction deadlock or conflict is about to happen, the
      current transaction is rolled back and an exception is raised. When this
      property is set false, the transaction is not rolled back. Only the
      latest statement that would cause the conflict is undone and an
      exception is raised. The property should not be changed unless the
      application can quickly perform an alternative statement and complete
      the transaction. It is provided for compatibility with other database
      engines which do not roll back the transaction upon deadlock. This
      command is also discussed in the <a class="link" href="#sessions-chapt" title="Chapter&nbsp;3.&nbsp;Sessions and Transactions">Sessions and Transactions</a> chapter.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>This is equivalent to the connection property
      <code class="literal">hsqldb.tx_conflict_rollback</code>.</p>
<a name="N14954" class="indexterm"></a>
<p>
<span class="bold"><strong>SET DATABASE DEFAULT ISOLATION
      LEVEL</strong></span>
</p>
<p>
<span class="emphasis"><em>set database default isolation level
      statement</em></span><code class="literal"> </code>
</p>
<p>
<code class="literal">&lt;set database default isolation level&gt; ::= SET
      DATABASE DEFAULT ISOLATION LEVEL { READ COMMITTED | SERIALIZABLE
      }</code>
</p>
<p>Sets the transaction isolation level for new sessions. The
      default is READ COMMITTED. Each session can also set its isolation
      level.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>This is equivalent to the connection property
      <code class="literal">hsqldb.tx_level</code>.</p>
<a name="N1496E" class="indexterm"></a>
<p>
<span class="bold"><strong>SET DATABASE TEXT TABLE
      DEFAULTS</strong></span>
</p>
<p>
<span class="emphasis"><em>set database text table defaults
      statement</em></span>
</p>
<p>
<code class="literal">&lt;set database text table defaults statement&gt; ::=
      SET DATABASE TEXT TABLE DEFAULTS &lt;character
      literal&gt;</code>
</p>
<p>An optional property to override default text table settings.
      The string literal has the same format as the string used for setting
      the data source of a text table, but without the file name. See the
      <a class="link" href="#texttables-chapt" title="Chapter&nbsp;5.&nbsp;Text Tables">Text Tables</a>
      chapter.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
</div>
<div class="section" title="SQL Conformance Settings">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="mtc_sql_settings"></a>SQL Conformance Settings</h3>
</div>
</div>
</div>
<p>These statements modify the level of conformance to the SQL
      Standard in different areas. The settings that specify SQL SYNTAX are
      for compatibility with other database engines and are FALSE by default.
      For all the rest of the settings, TRUE means better conformance to the
      Standard (unless the Standard defines the behaviour as implementation
      dependent). The default value of a few of these settings is FALSE, due
      to widespread non-conforming statements that are already in use in user
      applications or statements generated by object relational tools. So long
      as it is practical, it is best to set the non-conforming defaults to
      TRUE in order to improve the quality of the database
      application.</p>
<a name="N1498B" class="indexterm"></a>
<p>
<span class="bold"><strong>SET DATABASE SQL
      SIZE</strong></span>
</p>
<p>
<span class="emphasis"><em>set database sql size statement</em></span>
</p>
<p>
<code class="literal">&lt;set database sql size statement&gt; ::= SET
      DATABASE SQL SIZE { TRUE | FALSE }</code>
</p>
<p>Enable or disable enforcement of column sizes for CHAR and
      VARCHAR columns. The default is TRUE, meaning table definition must
      contain <code class="literal">VARCHAR(n)</code> instead of
      <code class="literal">VARCHAR</code>.</p>
<p>SQL Standard requires enforcement.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>This is equivalent to the connection property
      <code class="literal">sql.enforce_size</code>.</p>
<a name="N149AB" class="indexterm"></a>
<p>
<span class="bold"><strong>SET DATABASE SQL
      NAMES</strong></span>
</p>
<p>
<span class="emphasis"><em>set database sql names statement</em></span>
</p>
<p>
<code class="literal">&lt;set database sql names statement&gt; ::= SET
      DATABASE SQL NAMES { TRUE | FALSE }</code>
</p>
<p>Enable or disable full enforcement of the rule that prevents
      SQL keywords being used for database object names such as columns and
      tables. The default is <code class="literal">FALSE</code>, meaning
      disabled.</p>
<p>SQL Standard requires enforcement. <span class="emphasis"><em>It is better to
      enable this check, in order to improve the quality and correctness of
      SQL statements.</em></span>
</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>This is equivalent to the connection property
      <code class="literal">sql.enforce_names</code>.</p>
<a name="N149CA" class="indexterm"></a>
<p>
<span class="bold"><strong>SET DATABASE SQL REGULAR
      NAMES</strong></span>
</p>
<p>
<span class="emphasis"><em>set database sql regular names
      statement</em></span>
</p>
<p>
<code class="literal">&lt;set database sql regular names statement&gt; ::=
      SET DATABASE SQL REGULAR NAMES { TRUE | FALSE }</code>
</p>
<p>Enable or disable use of the underscore character at the
      beginning, or the dollar character anywhere in database object names
      such as columns and tables. The default is <code class="literal">TRUE</code>,
      meaning disabled.</p>
<p>SQL Standard does not allow the underscore character at the
      start of names, and does not allow the dollar character anywhere in a
      name. This setting can be changed for compatibility with existing
      database or for porting databases which include names that do not
      conform to the Standard.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>This is equivalent to the connection property
      <code class="literal">sql.regular_names</code>.</p>
<a name="N149E7" class="indexterm"></a>
<p>
<span class="bold"><strong>SET DATABASE SQL
      REFERENCES</strong></span>
</p>
<p>
<span class="emphasis"><em>set database sql references
      statement</em></span>
</p>
<p>
<code class="literal">&lt;set database sql references statement&gt; ::= SET
      DATABASE SQL REFERENCES { TRUE | FALSE }</code>
</p>
<p>This command can enable or disable full enforcement of the rule
      that prevents ambiguous column references in SQL statements (usually
      SELECT statements). A column reference is ambiguous when it is not
      qualified by a table name or table alias and can refer to more than one
      column in a JOIN list.</p>
<p>The property is <code class="literal">FALSE</code> by default.</p>
<p>SQL Standard requires enforcement. <span class="emphasis"><em>It is better to
      enable this check, in order to improve the quality and correctness of
      SQL statements.</em></span> When false, the first matching table is used
      to resolve the column reference.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>This is equivalent to the connection property
      <code class="literal">sql.enforce_refs</code>.</p>
<a name="N14A09" class="indexterm"></a>
<p>
<span class="bold"><strong>SET DATABASE SQL
      TYPES</strong></span>
</p>
<p>
<span class="emphasis"><em>set database sql types statement</em></span>
</p>
<p>
<code class="literal">&lt;set database sql types statement&gt; ::= SET
      DATABASE SQL TYPES { TRUE | FALSE }</code>
</p>
<p>This command can enable or disable full enforcement of the
      rules that prevents illegal type conversions and parameters or nulls
      without type in SQL statements (usually SELECT statements). For example
      an INTEGER column or a DATE column cannot be compared to a character
      string or searched with a LIKE expression when the property is
      <code class="literal">TRUE</code>.</p>
<p>The property is <code class="literal">FALSE</code> by default.</p>
<p>SQL Standard requires enforcement. <span class="emphasis"><em>It is better to
      enable this check, in order to improve the quality and correctness of
      SQL statements.</em></span>
</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>This is equivalent to the connection property
      <code class="literal">sql.enforce_type</code>.</p>
<a name="N14A2D" class="indexterm"></a>
<p>
<span class="bold"><strong>SET DATABASE SQL TDC
      DELETE</strong></span>
</p>
<p>
<span class="emphasis"><em>set database sql tdc delete
      statement</em></span>
</p>
<p>
<code class="literal">&lt;set database sql tdc delete statement&gt; ::= SET
      DATABASE SQL TDC DELETE { TRUE | FALSE }</code>
</p>
<p>This command can enable or disable full enforcement of the SQL
      Standard rules that prevents triggered data change exceptions caused by
      ON DELETE CASCADE clauses of foreign key constraint.</p>
<p>When there are multiple constraints, a row may be updated by
      one constraint and deleted by another constraint in the same operation.
      This is not allowed by default. Changing this to false allows such
      violations of the Standard to pass without an exception.</p>
<p>The property is <code class="literal">TRUE</code> by default.</p>
<p>SQL Standard requires enforcement, therefore this property
      shouldn't be changed unless an application written for a non-conforming
      RDBMS needs it.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>This is equivalent to the connection property
      <code class="literal">sql.enforce_tdc_delete</code>.</p>
<a name="N14A4E" class="indexterm"></a>
<p>
<span class="bold"><strong>SET DATABASE SQL TDC
      UPDATE</strong></span>
</p>
<p>
<span class="emphasis"><em>set database sql tdc update
      statement</em></span>
</p>
<p>
<code class="literal">&lt;set database sql tdc update statement&gt; ::= SET
      DATABASE SQL TDC UPDATE { TRUE | FALSE }</code>
</p>
<p>This command can enable or disable full enforcement of the SQL
      Standard rules that prevents triggered data change exceptions caused by
      multiple ON UPDATE or ON DELETE SET clauses of foreign key constraint.
      When there are multiple constraints, a field in a row may be updated by
      two constraints to different values in the same operation. This is not
      allowed by default. Changing this to <code class="literal">FALSE</code> allows
      such violations of the Standard to pass without an exception.</p>
<p>The property is <code class="literal">TRUE</code> by default.</p>
<p>SQL Standard requires enforcement, therefore this property
      shouldn't be changed unless an application written for a non-conforming
      RDBMS needs it.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>This is equivalent to the connection property
      <code class="literal">sql.enforce_tdc_update</code>.</p>
<a name="N14A70" class="indexterm"></a>
<p>
<span class="bold"><strong>SET DATABASE SQL TRANSLATE TTI
      TYPES</strong></span>
</p>
<p>
<span class="emphasis"><em>set database sql translate tti types
      statement</em></span>
</p>
<p>
<code class="literal">&lt;set database sql translate tti types statement&gt;
      ::= SET DATABASE SQL TRANSLATE TTI TYPES { TRUE | FALSE
      }</code>
</p>
<p>The JDBC Specification up to version 4.1 does not support some
      SQL Standard built-in types, therefore these types must be translated to
      a supported type when accessed through JDBC ResultSet and
      PreparedStatement methods.</p>
<p>If the property is true, the TIME / TIMESTAMP WITH TIME ZONE
      types and INTERVAL types are represented in JDBC methods of
      <code class="classname">ResultSetMetaData</code> and
      <code class="classname">DatabaseMetaData</code> as JDBC datetime types without
      time zone and the VARCHAR type respectively. The original type names are
      preserved.</p>
<p>The property is <code class="literal">TRUE</code> by default. If set to
      <code class="literal">FALSE</code>, the type codes for WITH TIME ZONE types will
      be SQL type codes as opposed to JDBC type codes.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>This is equivalent to the connection property
      <code class="literal">jdbc.translate_tti_types</code>.</p>
<a name="N14A98" class="indexterm"></a>
<p>
<span class="bold"><strong>SET DATABASE SQL CONCAT
      NULLS</strong></span>
</p>
<p>
<span class="emphasis"><em>set database sql concat nulls
      statement</em></span>
</p>
<p>
<code class="literal">&lt;set database sql concat nulls statement&gt; ::=
      SET DATABASE SQL CONCAT NULLS { TRUE | FALSE }</code>
</p>
<p>When the property is <code class="literal">TRUE</code>, concatenation of
      a null value with a not-null value results in a null value. When the
      property is <code class="literal">FALSE</code> this type of concatenation result
      in the not-null value.</p>
<p>Setting this property <code class="literal">FALSE</code> results in
      concatenation behaviour similar to Oracle or MS SQL Server.</p>
<p>SQL Standard requires a NULL result..</p>
<p>The property is <code class="literal">TRUE</code> by default.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>This is equivalent to the connection property
      <code class="literal">sql.concat_nulls</code>.</p>
<a name="N14AC2" class="indexterm"></a>
<p>
<span class="bold"><strong>SET DATABASE SQL UNIQUE
      NULLS</strong></span>
</p>
<p>
<span class="emphasis"><em>set database sql unique nulls
      statement</em></span>
</p>
<p>
<code class="literal">&lt;set database sql unique nulls statement&gt; ::=
      SET DATABASE SQL UNIQUE NULLS { TRUE | FALSE }</code>
</p>
<p>When the property is <code class="literal">TRUE</code>, with multi-column
      UNIQUE constraints, it is possible to insert multiple rows for which one
      or more of the values for the constraint columns is NULL. When the
      property is <code class="literal">FALSE</code>, if there is any not-null value in
      the columns, then the set of values is compared to the existing rows and
      if there is a match, an exception is thrown. The setting
      <code class="literal">FALSE</code>, makes the behaviour more restrictive. For
      example, inserting (1, null) twice is possible by default, but not
      possible when the property is <code class="literal">FALSE</code>.</p>
<p>Setting this property <code class="literal">FALSE</code> results in
      UNIQUE constraint behaviour similar to Oracle.</p>
<p>SQL Standard requires the default (TRUE) behaviour.</p>
<p>The property is <code class="literal">TRUE</code> by default.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>This is equivalent to the connection property
      <code class="literal">sql.unique_nulls</code>.</p>
<a name="N14AF2" class="indexterm"></a>
<p>
<span class="bold"><strong>SET DATABASE SQL CONVERT
      TRUNCATE</strong></span>
</p>
<p>
<span class="emphasis"><em>set database sql convert
      truncate</em></span>
</p>
<p>
<code class="literal">&lt;set database sql convert truncate statement&gt;
      ::= SET DATABASE SQL CONVERT TRUNCATE { TRUE | FALSE
      }</code>
</p>
<p>When the property is <code class="literal">TRUE</code>, conversion from a
      floating point value (a DOUBLE value) to an integral type always
      truncates the fractional part. When the property is
      <code class="literal">FALSE</code>, rounding takes place instead of truncation.
      For example, assigning the value 123456E-2 to an integer column will
      result in 1234 by default, but 1235 when the property is
      <code class="literal">FALSE</code>.</p>
<p>Standard SQL considers this behaviour implementation
      dependent.</p>
<p>The property is <code class="literal">TRUE</code> by default.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>This is equivalent to the connection property
      <code class="literal">sql.convert_trunc</code>.</p>
<a name="N14B1A" class="indexterm"></a>
<p>
<span class="bold"><strong>SET DATABASE SQL AVG
      SCALE</strong></span>
</p>
<p>
<span class="emphasis"><em>set database sql avg scale</em></span>
</p>
<p>
<code class="literal">&lt;set database sql avg scale&gt; ::= SET DATABASE
      SQL AVG SCALE &lt;numeric value&gt;</code>
</p>
<p>By default, the result of division and the AVG and MEDIAN
      aggregate functions has the same type as the aggregated type of the
      values. This includes the scale. The scale specified with this property
      is used if it is larger than the scale of the operation. For example,
      the average of 5 and 10 is 7 by default, but 7.50 if the scale is
      specified as 2. The result of 7/3 is 2 by default but 2.33 if the scale
      is specified as 2.</p>
<p>Standard SQL considers this behaviour implementation dependent.
      Some databases use a default scale larger than zero.</p>
<p>The property is <code class="literal">0</code> by default.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>This is equivalent to the connection property
      <code class="literal">sql.avg_scale</code>.</p>
<a name="N14B39" class="indexterm"></a>
<p>
<span class="bold"><strong>SET DATABASE SQL DOUBLE
      NAN</strong></span>
</p>
<p>
<span class="emphasis"><em>set database sql double nan</em></span>
</p>
<p>
<code class="literal">&lt;set database sql double nan&gt; ::= SET DATABASE
      SQL DOUBLE NAN { TRUE | FALSE }</code>
</p>
<p>When the property is <code class="literal">TRUE</code>, division of a
      floating point value (a DOUBLE value) by zero raises an exception. When
      the property is <code class="literal">FALSE</code>, a Java
      <code class="literal">Double.NaN</code>, <code class="literal">POSITIVE_INFINITY</code> or
      <code class="literal">NEGATIVE_INFINITY</code> value is returned.</p>
<p>Standard SQL requires an exception to be raised.</p>
<p>The property is <code class="literal">TRUE</code> by default.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>This is equivalent to the connection property
      <code class="literal">sql.double_nan</code>.</p>
<a name="N14B67" class="indexterm"></a>
<p>
<span class="bold"><strong>SET DATABASE SQL NULLS
      FIRST</strong></span>
</p>
<p>
<span class="emphasis"><em>set database sql nulls first</em></span>
</p>
<p>
<code class="literal">&lt;set database sql nulls first&gt; ::= SET DATABASE
      SQL NULLS FIRST { TRUE | FALSE }</code>
</p>
<p>When the property is <code class="literal">TRUE</code>, nulls appear
      before values in result sets with ORDER BY. When set FALSE, nulls appear
      after the values. Some databases, including PostgreSQL, Oracle and MS
      SQL Server, return nulls after the values.</p>
<p>The property is <code class="literal">TRUE</code> by default.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>This is equivalent to the connection property
      <code class="literal">sql.nulls_first</code>.</p>
<a name="N14B87" class="indexterm"></a>
<p>
<span class="bold"><strong>SET DATABASE SQL NULLS
      ORDER</strong></span>
</p>
<p>
<span class="emphasis"><em>set database sql nulls order</em></span>
</p>
<p>
<code class="literal">&lt;set database sql nulls order&gt; ::= SET DATABASE
      SQL NULLS ORDER { TRUE | FALSE }</code>
</p>
<p>When NULLS FIRST or NULLS LAST is used explicitly in the ORDER
      BY clause, this property is ignored.</p>
<p>When the property is <code class="literal">TRUE</code>, nulls appear
      according to the value of NULL FIRST property as described
      above.</p>
<p>When set <code class="literal">FALSE</code>, nulls appear according to
      the value of NULLS FIRST property when DESC is not used in the ORDER BY
      clause. But if DESC is used, the position of nulls is reversed. Some
      databases, including MySQL and Oracle, return nulls in this manner when
      DESC is used in ORDER BY.</p>
<p>The property is <code class="literal">TRUE</code> by default.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>This is equivalent to the connection property
      <code class="literal">sql.nulls_order</code>.</p>
<a name="N14BAE" class="indexterm"></a>
<p>
<span class="bold"><strong>SET DATABASE SQL
      IGNORECASE</strong></span>
</p>
<p>
<span class="emphasis"><em>set database sql ignorecase</em></span>
</p>
<p>
<code class="literal">&lt;set database sql ignorecase&gt; ::= SET DATABASE
      SQL IGNORECASE { TRUE | FALSE }</code>
</p>
<p>This property is <code class="literal">FALSE</code> by default and should
      only be used in special circumstances where compatibility with a
      different database is required.</p>
<p>When the property is <code class="literal">TRUE</code>, all declarations
      of <code class="literal">VARCHAR</code> columns in tables or other database
      objects are converted to <code class="literal">VARCHAR_IGNORECASE</code>. This has
      a global effect on the database, unlike the <code class="literal">SET
      IGNORECASE</code> statement which applies only to the current
      session.</p>
<p>The property is <code class="literal">FALSE</code> by default.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>This is equivalent to the connection property
      <code class="literal">sql.ignore_case</code>.</p>
<a name="N14BDC" class="indexterm"></a>
<p>
<span class="bold"><strong>SET DATABASE SQL SYNTAX
      DB2</strong></span>
</p>
<p>
<span class="emphasis"><em>set database sql syntax DB2</em></span>
</p>
<p>
<code class="literal">&lt;set database sql syntax DB2 statement&gt; ::= SET
      DATABASE SQL SYNTAX DB2 { TRUE | FALSE }</code>
</p>
<p>This property, when set TRUE, enables support for some elements
      of DB2 syntax. Single-row SELECT statements (<code class="literal">SELECT
      &lt;expression list&gt;</code> without the FROM clause) are supported
      and treated as the SQL Standard equivalent, <code class="literal">VALUES
      &lt;expression list&gt;</code>. The DUAL table is supported, as well
      as the ROWNUM pseudo-column. BINARY type definitions such as VARCHAR(L)
      FOR BIT DATA are supported. Empty DEFAULT clauses in column definitions
      are supported.</p>
<p>The property is <code class="literal">FALSE</code> by default.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>This is equivalent to the connection property
      <code class="literal">sql.syntax_db2</code>.</p>
<a name="N14BFF" class="indexterm"></a>
<p>
<span class="bold"><strong>SET DATABASE SQL SYNTAX
      MSS</strong></span>
</p>
<p>
<span class="emphasis"><em>set database sql syntax MSS</em></span>
</p>
<p>
<code class="literal">&lt;set database sql syntax MSS statement&gt; ::= SET
      DATABASE SQL SYNTAX MSS { TRUE | FALSE }</code>
</p>
<p>This property, when set TRUE, enables support for some elements
      of SQLServer syntax. Single-row SELECT statements (<code class="literal">SELECT
      &lt;expression list&gt;</code> without the FROM clause) are supported
      and treated as the SQL Standard equivalent, <code class="literal">VALUES
      &lt;expression list&gt;</code>. The parameters of CONVERT() function
      are switched in this mode.</p>
<p>The property is <code class="literal">FALSE</code> by default.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>This is equivalent to the connection property
      <code class="literal">sql.syntax_mss</code>.</p>
<a name="N14C22" class="indexterm"></a>
<p>
<span class="bold"><strong>SET DATABASE SQL SYNTAX
      MYS</strong></span>
</p>
<p>
<span class="emphasis"><em>set database sql syntax MYS</em></span>
</p>
<p>
<code class="literal">&lt;set database sql syntax MYS statement&gt; ::= SET
      DATABASE SQL SYNTAX MYS { TRUE | FALSE }</code>
</p>
<p>This property, when set TRUE, enables support for some elements
      of MySQL syntax. The TEXT data type is translated to
      LONGVARCHAR.</p>
<p>In CREATE TABLE statements, [NOT NULL | NULL] can be used
      immediately after the column type name and before the DEFAULT clause.
      AUTO_INCREMENT is translated to the GENERATED BY DEFAULT AS IDENTITY
      clause.</p>
<p>Single-row SELECT statements (<code class="literal">SELECT &lt;expression
      list&gt;</code> without the FROM clause) are supported and treated as
      the SQL Standard equivalent, <code class="literal">VALUES &lt;expression
      list&gt;</code>.</p>
<p>The property is <code class="literal">FALSE</code> by default.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>This is equivalent to the connection property
      <code class="literal">sql.syntax_mys</code>.</p>
<a name="N14C49" class="indexterm"></a>
<p>
<span class="bold"><strong>SET DATABASE SQL SYNTAX
      ORA</strong></span>
</p>
<p>
<span class="emphasis"><em>set database sql syntax ORA</em></span>
</p>
<p>
<code class="literal">&lt;set database sql syntax ORA statement&gt; ::= SET
      DATABASE SQL SYNTAX ORA { TRUE | FALSE }</code>
</p>
<p>This property, when set TRUE, enables support for some elements
      of Oracle syntax. The DUAL table is supported, together with ROWNUM,
      NEXTVAL and CURRVAL syntax and semantics.</p>
<p>The non-standard types are translated to supported standard
      types. BINARY_DOUBLE and BINARY_FLOAT are translated to DOUBLE. LONG RAW
      and RAW are translated to VARBINARY with long or medium length limits.
      LONG and VARCHAR2 are translated to VARCHAR with long or medium length
      limits. NUMBER is translated to DECIMAL. Some extra type conversions and
      no-arg functions are also allowed in this mode.</p>
<p>The property is <code class="literal">FALSE</code> by default.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>This is equivalent to the connection property
      <code class="literal">sql.syntax_ora</code>.</p>
<a name="N14C68" class="indexterm"></a>
<p>
<span class="bold"><strong>SET DATABASE SQL SYNTAX
      PGS</strong></span>
</p>
<p>
<span class="emphasis"><em>set database sql syntax PGS</em></span>
</p>
<p>
<code class="literal">&lt;set database sql syntax PGS statement&gt; ::= SET
      DATABASE SQL SYNTAX PGS { TRUE | FALSE }</code>
</p>
<p>This property, when set TRUE, enables support for some elements
      of PosgtreSQL syntax. The TEXT data type is translated to LONGVARCHAR,
      while the SERIAL data types is translated to BIGINT together with
      GENERATED BY DEFAULT AS IDENTITY.</p>
<p>Single-row SELECT statements (<code class="literal">SELECT &lt;expression
      list&gt;</code> without the FROM clause) are supported and treated as
      the SQL Standard equivalent, <code class="literal">VALUES &lt;expression
      list&gt;</code>.</p>
<p>The functions <code class="literal">NEXTVAL(&lt;sequence name
      string&gt;)</code>, <code class="literal">CURRVAL(&lt;sequence name
      string&gt;)</code> and <code class="literal">LASTVAL()</code> are supported in
      this compatibility mode.</p>
<p>The property is <code class="literal">FALSE</code> by default.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>This is equivalent to the connection property
      <code class="literal">sql.syntax_pgs</code>.</p>
<a name="N14C98" class="indexterm"></a>
<p>
<span class="bold"><strong>SET DATABASE REFERENTIAL
      INTEGRITY</strong></span>
</p>
<p>
<span class="emphasis"><em>set database referential integrity
      statement</em></span>
</p>
<p>
<code class="literal">&lt;set database referential integrity statement&gt;
      ::= SET DATABASE REFERENTIAL INTEGRITY { TRUE | FALSE
      }</code>
</p>
<p>This command enables or disables the enforcement of referential
      integrity constraints (foreign key constraints), check constraints apart
      from NOT NULL and execution of triggers. By default, all constraints are
      checked.</p>
<p>The only legitimate use of this statement is before importing
      large amounts of external data into tables that have existing FOREIGN
      KEY constraints. After import, the statement must be used again to
      enable constraint enforcement.</p>
<p>If you are not sure the data conforms to the constraints, run
      queries to verify all rows conform to the FOREIGN KEY constraints and
      take appropriate actions for the rows that do not conform.</p>
<p>A query example to return the rows in a foreign key table that
      have no parent is given below:</p>
<div class="example">
<a name="N14CAF"></a>
<p class="title">
<b>Example&nbsp;11.6.&nbsp;Finding foreign key rows with no parents after a bulk
        import</b>
</p>
<div class="example-contents">
<pre class="screen"> SELECT * FROM foreign_key_table LEFT OUTER JOIN primary_key_table 
   ON foreign_key_table.fk_col = primary_key_table.pk_col WHERE primary_key_table.pk_col IS NULL</pre>
</div>
</div>
<br class="example-break">
<p>Only a user with the DBA role can execute this
      statement.</p>
</div>
<div class="section" title="Cache, Persistence and Files Settings">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="mtc_cache_persistence"></a>Cache, Persistence and Files Settings</h3>
</div>
</div>
</div>
<p>These statements control the memory and other settings for
      database persistence.</p>
<a name="N14CBC" class="indexterm"></a>
<p>
<span class="bold"><strong>SET FILES BACKUP INCREMENT
      </strong></span>
</p>
<p>
<span class="emphasis"><em>set files backup increment
      statement</em></span>
</p>
<p>
<code class="literal">&lt;set files backup increment statement&gt; ::= SET
      FILES BACKUP INCREMENT { TRUE | FALSE }</code>
</p>
<p>Older versions of HSQLDB perform a backup of the .data file
      before its contents are modified and the whole .data file is saved in a
      compressed form when a CHECKPOINT or SHUTDOWN is performed. This takes a
      long time when the size of the database exceeds 100 MB or so (on an
      average 2010 computer, you can expect a backup speed of 20MB per second
      or more).</p>
<p>The alternative is backup in increments, just before some part
      of the .data file is modified. In this mode, no backup is performed at
      CHECKPOINT or SHUTDOWN. This mode is preferred for large databases which
      are opened and closed frequently.</p>
<p>The default mode is <code class="literal">TRUE</code>. If the old method
      of backup is preferred, the mode can be set
      <code class="literal">FALSE</code>.</p>
<p>Warning: The old, non-incremental setting, FALSE, shouldn't be
      used at all when the data file is larger than 4GB. If it is used, the
      data file is not fully backed up and can result in corruption. The zip
      compression method is used in this mode and it is limited to 4GB
      size.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>This is equivalent to the connection property
      <code class="literal">hsqldb.inc_backup</code>.</p>
<a name="N14CE0" class="indexterm"></a>
<p>
<span class="bold"><strong>SET FILES CACHE ROWS</strong></span>
</p>
<p>
<span class="emphasis"><em>set files cache rows statement</em></span><code class="literal">
      </code>
</p>
<p>
<code class="literal">&lt;set files cache rows statement&gt; ::= SET FILES
      CACHE ROWS &lt;unsigned integer literal&gt;</code>
</p>
<p>Sets the maximum number of rows (of CACHED tables) held in the
      memory cache. The default is 50000 rows.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>This is equivalent to the connection property
      <code class="literal">hsqldb.cache_rows</code>.</p>
<a name="N14CFA" class="indexterm"></a>
<p>
<span class="bold"><strong>SET FILES CACHE SIZE</strong></span>
</p>
<p>
<span class="emphasis"><em>set files cache size statement</em></span><code class="literal">
      </code>
</p>
<p>
<code class="literal">&lt;set files cache size statement&gt; ::= SET FILES
      CACHE SIZE &lt;unsigned integer literal&gt;</code>
</p>
<p>Sets maximum amount of data (of CACHED tables) in kilobytes
      held in the memory cache. The default is 10000 kilobytes. Note the
      amount of memory used is larger than this amount, which does not account
      for Java object size overheads.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>This is equivalent to the connection property
      <code class="literal">hsqldb.cache_size</code>.</p>
<a name="N14D14" class="indexterm"></a>
<p>
<span class="bold"><strong>SET FILES DEFRAG</strong></span>
</p>
<p>
<span class="emphasis"><em>set files defrag statement</em></span>
</p>
<p>
<code class="literal">&lt;set files defrag statement&gt; ::= SET FILES
      DEFRAG &lt;unsigned integer literal&gt;</code>
</p>
<p>Sets the threshold for performing a DEFRAG during a checkpoint.
      The <code class="literal">&lt;unsigned integer literal&gt;</code> is the
      percentage of abandoned space in the <code class="literal">*.data</code> file.
      When a CHECKPOINT is performed either as a result of the
      <code class="literal">.log</code> file reaching the limit set by <code class="literal">SET
      FILES LOG SIZE m</code>, or by the user issuing a CHECKPOINT command,
      the amount of space abandoned since the database was opened is checked
      and if it is larger than specified percentage, a CHECKPOINT DEFRAG is
      performed instead of a CHECKPOINT.</p>
<p>The default is 0, which indicates no DEFRAG. Useful values are
      between 10 to 50.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>This is equivalent to the connection property
      <code class="literal">hsqldb.defrag_limit</code>.</p>
<a name="N14D3A" class="indexterm"></a>
<p>
<span class="bold"><strong>SET FILES LOG</strong></span>
</p>
<p>
<span class="emphasis"><em>set files log statement</em></span>
</p>
<p>
<code class="literal">&lt;set files log statement&gt; ::= SET FILES LOG {
      TRUE | FALSE }</code>
</p>
<p>Sets logging of database operations on or off. Turning logging
      off is for special usage, such as temporary cache usage. The default is
      TRUE.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>This is equivalent to the connection property
      <code class="literal">hsqldb.log_data</code>.</p>
<a name="N14D52" class="indexterm"></a>
<p>
<span class="bold"><strong>SET FILES LOG SIZE</strong></span>
</p>
<p>
<span class="emphasis"><em>set files log size statement</em></span>
</p>
<p>
<code class="literal">&lt;set files log size statement&gt; ::= SET FILES LOG
      SIZE &lt;unsigned integer literal&gt;</code>
</p>
<p>Sets the maximum size in MB of the <code class="literal">*.log</code>
      file to the specified value. The default maximum size is 50 MB. If the
      value is zero, no limit is used for the size of the file. When the size
      of the file reaches this value, a CHECKPOINT is performed and the the
      <code class="literal">*.log</code> file is cleared to size 0.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>This is equivalent to the connection property
      <code class="literal">hsqldb.log_size</code>.</p>
<a name="N14D70" class="indexterm"></a>
<p>
<span class="bold"><strong>SET FILES NIO</strong></span>
</p>
<p>
<span class="emphasis"><em>set files nio</em></span>
</p>
<p>
<code class="literal">&lt;set files nio statement&gt; ::= SET FILES NIO {
      TRUE | FALSE }</code>
</p>
<p>Sets the access method of the .data file. The default is TRUE
      and uses the Java nio classes to access the file via memory-mapped
      buffers.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>This is equivalent to the connection property
      <code class="literal">hsqldb.nio_data_file</code>.</p>
<a name="N14D88" class="indexterm"></a>
<p>
<span class="bold"><strong>SET FILES NIO SIZE</strong></span>
</p>
<p>
<span class="emphasis"><em>set files nio size</em></span>
</p>
<p>
<code class="literal">&lt;set files nio size statement&gt; ::= SET FILES NIO
      SIZE &lt;unsigned integer literal&gt;</code>
</p>
<p>Sets The maximum size of .data file in megabytes that can use
      the nio access method. When the file gets larger than this limit,
      non-nio access methods are used. Values 64, 128, 256, 512, 1024 and
      larger multiples of 512 can be used. The default is 256MB.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>This is equivalent to the connection property
      <code class="literal">hsqldb.nio_max_size</code>.</p>
<a name="N14DA0" class="indexterm"></a>
<p>
<span class="bold"><strong>SET FILES WRITE
      DELAY</strong></span>
</p>
<p>
<span class="emphasis"><em>set files write delay statement</em></span>
</p>
<p>
<code class="literal">&lt;set files write delay statement&gt; ::= SET FILES
      WRITE DELAY {{ TRUE | FALSE } | &lt;seconds value&gt; | &lt;milliseconds
      value&gt; MILLIS}</code>
</p>
<p>Set the WRITE DELAY property of the database. The WRITE DELAY
      controls the frequency of file sync for the log file. When WRITE_DELAY
      is set to FALSE or 0, the sync takes place immediately at each COMMIT.
      WRITE DELAY TRUE performs the sync once every 0.5 seconds (which is the
      default). A numeric value can be specified instead.</p>
<p>The purpose of this command is to control the amount of data loss
      in case of a total system crash. A delay of 1 second means at most the
      data written to disk during the last second before the crash is lost.
      All data written prior to this has been synced and should be
      recoverable.</p>
<p>A write delay of 0 impacts performance in high load situations, as
      the engine has to wait for the file system to catch up.</p>
<p>To avoid this, you can set write delay down to 10
      milliseconds.</p>
<p>Each time the SET FILES WRITE DELAY statement is executed with any
      value, a sync is immediately performed.</p>
<p>Only a user with the DBA role can execute this statement.</p>
<p>This is equivalent to the connection properties
      <code class="literal">hsqldb.write_delay</code> and
      <code class="literal">hsqldb.write_delay_millis</code>.</p>
<a name="N14DC3" class="indexterm"></a>
<p>
<span class="bold"><strong>SET FILES SCALE</strong></span>
</p>
<p>
<span class="emphasis"><em>set files scale</em></span>
</p>
<p>
<code class="literal">&lt;set files scale statement&gt; ::= SET FILES SCALE
      &lt;scale value&gt;</code>
</p>
<p>Changes the scale factor for the .data file. The default scale
      is 8 and allows 16GB of data storage capacity. The scale can be
      increased in order to increase the maximum data storage capacity. The
      scale values 8, 16, 32, 64, 128, 256, 512, 1024 are allowed. Scale value
      1024 allows a maximum capacity of 2 TB.</p>
<p>This command can be used only when there is no data in CACHED
      tables. This is equivalent to the connection property
      <code class="literal">hsqldb.cache_file_scale</code>.</p>
<p>The scale factor indicates the size of the unit of storage of
      data in bytes. For example, with a scale factor of 128, a row containing
      a small amount of data will use 128 bytes. Larger rows may use multiple
      units of 128 bytes.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>This is equivalent to the connection property
      <code class="literal">hsqldb.cache_file_scale</code>.</p>
<a name="N14DE2" class="indexterm"></a>
<p>
<span class="bold"><strong>SET FILES LOB SCALE</strong></span>
</p>
<p>
<span class="emphasis"><em>set files lob scale</em></span>
</p>
<p>
<code class="literal">&lt;set files lob scale statement&gt; ::= SET FILES
      LOB SCALE &lt;scale value&gt;</code>
</p>
<p>Changes the scale factor for the .lobs file. The scale is
      interpreted in kilobytes. The default scale is 32 and allows 64TB of lob
      data storage capacity. The scale can be reduced in order to improve
      storage efficiency. If the lobs are a lot smaller than 32 kilobytes,
      reducing the scale will reduce wasted space. The scale values 1, 2, 4,
      8, 16, 32 are allowed. For example if the average size of lobs is 4
      kilobytes, the default scale of 32 will result in 28KB wasted space for
      each lob. Reducing the lob scale to 2 will result in average 1KB wasted
      space for each lob.</p>
<p>This command can be used only when there is no lob in the
      database.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>This is equivalent to the connection property
      <code class="literal">hsqldb.lob_file_scale</code>.</p>
<a name="N14DFC" class="indexterm"></a>
<p>
<span class="bold"><strong>SET FILES LOB
      COMPRESSED</strong></span>
</p>
<p>
<span class="emphasis"><em>set files lob compressed</em></span>
</p>
<p>
<code class="literal">&lt;set files lob compressed statement&gt; ::= SET
      FILES LOB COMPRESSED { TRUE | FALSE }</code>
</p>
<p>By default, lobs are not compressed for storage. When this
      setting is <code class="literal">TRUE</code>, all BLOB and CLOB values stored in
      the database are compressed. Compression reduces the storage size but
      increases the access time.</p>
<p>This command can be used only when there is no lob in the
      database.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>This is equivalent to the connection property
      <code class="literal">hsqldb.lob_compressed</code>.</p>
<a name="N14E19" class="indexterm"></a>
<p>
<span class="bold"><strong>SET FILES SCRIPT
      FORMAT</strong></span>
</p>
<p>
<span class="emphasis"><em>set files script format</em></span>
</p>
<p>
<code class="literal">&lt;set files script format statement&gt; ::= SET
      FILES SCRIPT FORMAT { TEXT | COMPRESSED }</code>
</p>
<p>Changes the compression setting for database scripts. The
      default is text. Using COMPRESSED results in the storage of the .script
      file in gzip compressed form. Using this command causes a
      CHECKPOINT.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<a name="N14E2C" class="indexterm"></a>
<p>
<span class="bold"><strong>SET TABLE TYPE</strong></span>
</p>
<p>
<span class="emphasis"><em>set table type</em></span>
</p>
<p>
<code class="literal">&lt;set table type statement&gt; ::= SET TABLE
      &lt;table name&gt; TYPE { MEMORY | CACHED }</code>
</p>
<p>Changes the storage type of an existing table between CACHED
      and MEMORY types.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
</div>
<div class="section" title="Authentication Settings">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="mtc_authntication_settings"></a>Authentication Settings</h3>
</div>
</div>
</div>
<p>Two settings are available for authentication control.</p>
<p>When the default password authentication is used, the passwords
      can be checked for complexity according to administrative rules</p>
<a name="N14E47" class="indexterm"></a>
<p>
<span class="bold"><strong>SET DATABASE PASSWORD CHECK
      FUNCTION</strong></span>
</p>
<p>
<span class="emphasis"><em>set database password check
      function</em></span>
</p>
<p>
<code class="literal">&lt;set database password check function statement&gt;
      ::= SET DATABASE PASSWORD CHECK FUNCTION { &lt;routine body&gt; | NONE
      }</code>
</p>
<p>The routine body is the body of a function that has a VARCHAR
      parameter and returns a BOOLEAN. This function checks the
      <code class="literal">PASSWORD</code> submitted as parameter and returns TRUE if
      it conforms to complexity checks, or FALSE, if it does not.</p>
<p>The <code class="literal">&lt;routine body&gt;</code> can be an SQL block
      or an external Java function reference. This is covered in the <a class="link" href="#sqlroutines-chapt" title="Chapter&nbsp;8.&nbsp;SQL-Invoked Routines">SQL-Invoked Routines</a>
      chapter</p>
<p>To disable this mechanism, the token <code class="literal">NONE</code>
      can be specified instead of the <code class="literal">&lt;routine
      body&gt;</code>.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<p>In the examples below, an SQL function and a Java function are
      used.</p>
<pre class="programlisting"> SET DATABASE PASSWORD CHECK FUNCTION
   BEGIN ATOMIC
     IF CHAR_LENGTH(PASSWORD) &gt; 6 THEN
       RETURN TRUE;
     ELSE 
       RETURN FALSE;
     END IF;
   END

 SET DATABASE PASSWORD CHECK FUNCTION EXTERNAL NAME 'CLASSPATH:org.anorg.access.AccessClass.accessMethod'

 // the Java method is defined like this
 public static boolean accessMethod(String param) {
     return param != null &amp;&amp; param.length &gt; 6;
 }
</pre>
<p>It is possible to replace the default password authentication
      completely with a function that uses external authentication servers,
      such as LDAP. This function is called each time a user connects to the
      database.</p>
<a name="N14E74" class="indexterm"></a>
<p>
<span class="bold"><strong>SET DATABASE AUTHENTICATION
      FUNCTION</strong></span>
</p>
<p>
<span class="emphasis"><em>set database authentication
      function</em></span>
</p>
<p>
<code class="literal">&lt;set database authentication function statement&gt;
      ::= SET DATABASE AUTHENTICATION FUNCTION { &lt;external body
      reference&gt; | NONE }</code>
</p>
<p>The routine body is an external Java function reference. This
      function has three String parameters. The first parameter is the unique
      name of the database, the second parameter the user name, and the third
      parameter the password.</p>
<p>External authentication can be used in two different patterns.
      In the first pattern, user names must be stored in the database. In the
      second pattern, user names shouldn't be stored in the database and any
      names that are stored in the database are ignored.</p>
<p>In both patterns, the username and password are checked by the
      authentication function. If the function throws a runtime exception then
      authentication fails.</p>
<p>In the first pattern, the function always returns null if
      authentication is successful.</p>
<p>In the second pattern, the function returns a list of role
      names that have been granted to the user. These roles must match the
      ROLE objects that have been defined in the database.</p>
<p>The Java function should return an instance of
      org.hsqldb.jdbc.JDBCArrayBasic constructed with a String[] argument that
      contains the role names.</p>
<p>Only a user with the DBA role can execute this
      statement.</p>
<pre class="programlisting"> SET DATABASE AUTHENTICATION FUNCTION EXTERNAL NAME 'CLASSPATH:org.anorg.access.AccessClass.accessExernalMethod'

 // the Java method is defined like this
 public static java.sql.Array accessExternalMethod(String database, String user, String password) {
     if (externalCheck(database, user, password) {
         return null;
     }
     throw new RuntimeException("failed to authenticate");
 }
</pre>
</div>
</div>
</div>
<div class="chapter" title="Chapter&nbsp;12.&nbsp;Properties">
<div class="titlepage">
<div>
<div>
<h2 class="title">
<a name="dbproperties-chapt"></a>Chapter&nbsp;12.&nbsp;Properties</h2>
</div>
<div>
<div class="authorgroup">
<div class="author">
<h3 class="author">
<span class="firstname">Fred</span> <span class="surname">Toussi</span>
</h3>
<div class="affiliation">
<span class="orgname">The HSQL Development Group<br>
</span>
</div>
</div>
</div>
</div>
<div>
<p class="releaseinfo">$Revision: 5260 $</p>
</div>
<div>
<div class="legalnotice" title="Legal Notice">
<a name="N14EB9"></a>
<p>Copyright 2002-2012 Fred Toussi. Permission is granted to
      distribute this document without any alteration under the terms of the
      HSQLDB license. Additional permission is granted to the HSQL Development
      Group to distribute this document with or without alterations under the
      terms of the HSQLDB license.</p>
</div>
</div>
<div>
<p class="pubdate">2014-02-13 18:21:41-0500</p>
</div>
</div>
</div>
<div class="toc">
<p>
<b>Table of Contents</b>
</p>
<dl>
<dt>
<span class="section"><a href="#dpc_connection_url">Connection URL</a></span>
</dt>
<dt>
<span class="section"><a href="#dpc_variables_url">Variables In Connection URL</a></span>
</dt>
<dt>
<span class="section"><a href="#dpc_connection_props">Connection properties</a></span>
</dt>
<dt>
<span class="section"><a href="#dpc_db_props_url">Database Properties in Connection URL and Properties</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#dpc_sql_conformance">SQL Conformance Properties</a></span>
</dt>
<dt>
<span class="section"><a href="#dpc_db_operations">Database Operations Properties</a></span>
</dt>
<dt>
<span class="section"><a href="#dpc_db_file_mem">Database File and Memory Properties</a></span>
</dt>
<dt>
<span class="section"><a href="#dpc_crypt_props">Crypt Properties</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#dpc_system_props">System Properties</a></span>
</dt>
</dl>
</div>
<div class="section" title="Connection URL">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="dpc_connection_url"></a>Connection URL</h2>
</div>
</div>
</div>
<p>The normal method of accessing a HyperSQL catalog is via the JDBC
    Connection interface. An introduction to different methods of providing
    database services and accessing them can be found in the <a class="link" href="#sqlgeneral-chapt" title="Chapter&nbsp;2.&nbsp;SQL Language">SQL Language</a> chapter.
    Details and examples of how to connect via JDBC are provided in our
    JavaDoc for <code class="classname"><a class="classname" href="#JDBCConnection.html-link">
    JDBCConnection</a></code>.</p>
<p>A uniform method is used to distinguish between different types of
    connection. The common driver identifier is
    <code class="literal">jdbc:hsqldb:</code> followed by a protocol identifier
    (<code class="literal">mem: file: res: hsql: http: hsqls: https:</code>) then
    followed by host and port identifiers in the case of servers, then
    followed by database identifier. Additional property / value pairs can be
    appended to the end of the URL, separated with semicolons.</p>
<div class="table">
<a name="N14ED2"></a>
<p class="title">
<b>Table&nbsp;12.1.&nbsp;Memory Database URL</b>
</p>
<div class="table-contents">
<table summary="Memory Database URL" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col align="left" class="c1">
<col align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Driver and Protocol</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Host and Port Example</th><th style="border-bottom: 0.5pt solid ; " align="left">Database Example</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top">
<table summary="Simple list" border="0" class="simplelist">
<tr>
<td><code class="literal">jdbc:hsqldb:mem:</code></td>
</tr>
</table>
</td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top">not available</td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">
<table summary="Simple list" border="0" class="simplelist">
<tr>
<td><code class="literal">accounts</code></td>
</tr>
</table>
</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>Lowercase, single-word
            identifier creates the in-memory database when the first
            connection is made. Subsequent use of the same Connection URL
            connects to the existing DB.</p> 
<p>The old form for the
            URL, <code class="literal">jdbc:hsqldb:.</code> creates or connects to the
            same database as the new form for the URL,
            <code class="literal">jdbc:hsqldb:mem:.</code>
</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N14F08"></a>
<p class="title">
<b>Table&nbsp;12.2.&nbsp;File Database URL</b>
</p>
<div class="table-contents">
<table summary="File Database URL" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col align="left" class="c1">
<col align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Driver and Protocol</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Host and Port Example</th><th style="border-bottom: 0.5pt solid ; " align="left">Database Example</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top">
<table summary="Simple list" border="0" class="simplelist">
<tr>
<td><code class="literal">jdbc:hsqldb:file:</code></td>
</tr>
</table>
</td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top">not available</td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">
<table summary="Simple list" border="0" class="simplelist">
<tr>
<td><code class="literal">accounts</code></td>
</tr>
<tr>
<td><code class="literal">/opt/db/accounts</code></td>
</tr>
<tr>
<td><code class="literal">C:/data/mydb</code></td>
</tr>
</table>
</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>The file path specifies the
            database files. It should consist of a relative or absolute path
            to the directory containing the database files, followed by a '/'
            and the database name. In the above examples the first one refers
            to a set of mydb.* files in the directory where the
            <code class="literal">java</code>command for running the application was
            issued. The second and third examples refer to absolute paths on
            the host machine: For example, files named accounts.* in the
            directory /opt/db for the accounts database.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N14F3F"></a>
<p class="title">
<b>Table&nbsp;12.3.&nbsp;Resource Database URL</b>
</p>
<div class="table-contents">
<table summary="Resource Database URL" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col align="left" class="c1">
<col align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Driver and Protocol</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Host and Port Example</th><th style="border-bottom: 0.5pt solid ; " align="left">Database Example</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top">
<table summary="Simple list" border="0" class="simplelist">
<tr>
<td><code class="literal">jdbc:hsqldb:res:</code></td>
</tr>
</table>
</td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top">not available</td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">
<table summary="Simple list" border="0" class="simplelist">
<tr>
<td><code class="literal">/adirectory/dbname</code></td>
</tr>
</table>
</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">Database files can be loaded from
            one of the jars specified as part of the <code class="literal">Java</code>
            command the same way as resource files are accessed in Java
            programs. The <code class="literal">/adirectory</code> above stands for a
            directory in one of the jars.</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N14F72"></a>
<p class="title">
<b>Table&nbsp;12.4.&nbsp;Server Database URL</b>
</p>
<div class="table-contents">
<table summary="Server Database URL" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col align="left" class="c1">
<col align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Driver and Protocol</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Host and Port Example</th><th style="border-bottom: 0.5pt solid ; " align="left">Database Example</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top">
<table summary="Simple list" border="0" class="simplelist">
<tr>
<td><code class="literal">jdbc:hsqldb:hsql:</code></td>
</tr>
<tr>
<td><code class="literal">jdbc:hsqldb:hsqls:</code></td>
</tr>
<tr>
<td><code class="literal">jdbc:hsqldb:http:</code></td>
</tr>
<tr>
<td><code class="literal">jdbc:hsqldb:https:</code></td>
</tr>
</table>
</td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top">
<table summary="Simple list" border="0" class="simplelist">
<tr>
<td><code class="literal">//localhost</code></td>
</tr>
<tr>
<td><code class="literal">//192.0.0.10:9500</code></td>
</tr>
<tr>
<td><code class="literal">//dbserver.somedomain.com</code></td>
</tr>
</table>
</td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">
<table summary="Simple list" border="0" class="simplelist">
<tr>
<td><code class="literal">/an_alias</code></td>
</tr>
<tr>
<td><code class="literal">/enrolments</code></td>
</tr>
<tr>
<td><code class="literal">/quickdb</code></td>
</tr>
</table>
</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>The host and port specify
            the IP address or host name of the server and an optional port
            number. The database to connect to is specified by an alias. This
            alias is a lowercase string defined in the
            <code class="filename">server.properties</code> file to refer to an actual
            database on the file system of the server or a transient,
            in-memory database on the server. The following example lines in
            <code class="filename">server.properties</code> or
            <code class="filename">webserver.properties</code> define the database
            aliases listed above and accessible to clients to refer to
            different file and in-memory databases.</p> 
<p>The old form
            for the server URL, e.g.,
            <code class="literal">jdbc:hsqldb:hsql//localhost</code> connects to the
            same database as the new form for the URL,
            <code class="literal">jdbc:hsqldb:hsql//localhost/</code> where the alias is
            a zero length string.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
</div>
<div class="section" title="Variables In Connection URL">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="dpc_variables_url"></a>Variables In Connection URL</h2>
</div>
</div>
</div>
<p>Two types of variables are allowed for file: database URLs. These
    properties have an effect only if used for the first connection to the
    database (the connection which opens the database). When running a server,
    these variables have no effect on the connection URL but can be appended
    to the database path URL in server.properties or the server command
    line.</p>
<p>If the database part of a file: database begins with
    <code class="literal">~/</code> or <code class="literal">~\</code> the tilde character is
    replaced with the value of the system property
    <code class="literal">"user.home"</code> resulting in the database being created or
    accessed in this directory, or one of its subdirectories. In the examples
    below, the database files for <code class="literal">mydb</code> and
    <code class="literal">filedb</code> are located in the user's home directory.</p>
<pre class="programlisting"> jdbc:hsqldb:file:~/mydb
 jdbc:hsqldb:file:~/filedb;shutdown=true
</pre>
<p>If the database URL contains a string in the form of
    <code class="literal">${propname}</code> then the sequence of characters is replaced
    with the system property with the given name. For example you can use this
    in the URL of a database that is used in a web application and define the
    system property, "propname" in the web application properties. In the
    example below, the string <code class="literal">${mydbpath}</code> is replaced with
    the value of the property, <code class="literal">mydbpath</code>
</p>
<pre class="programlisting"> jdbc:hsqldb:file:${mydbpath}</pre>
</div>
<div class="section" title="Connection properties">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="dpc_connection_props"></a>Connection properties</h2>
</div>
</div>
</div>
<p>Each JDBC Connection to a database can specify connection
    properties. The properties <span class="property">user</span> and
    <span class="property">password</span> are always required. The following optional
    properties can also be used.</p>
<p>Connection properties are specified either by establishing the
    connection via the method call below, or the property can be appended to
    the full Connection URL. The first three of these properties can be used
    for any connection, including connection to a Server but the other three
    have an effect only with the first connection to a file: or mem: database,
    or when appended to the database path URL in server.properties or the
    server command line.</p>
<pre class="programlisting"> DriverManager.getConnection (String url, Properties info);</pre>
<div class="table">
<a name="N15000"></a>
<p class="title">
<b>Table&nbsp;12.5.&nbsp;User and Password</b>
</p>
<div class="table-contents">
<table summary="User and Password" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">user</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">SA</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">user name</td>
</tr>
<tr>
<td style="border-bottom: 0.5pt solid ; " colspan="3" align="left" valign="top">
<p>Standard property. This
            property is case sensitive. Example below:</p>
<pre class="programlisting"> jdbc:hsqldb:file:enrolments;user=aUserName;ifexists=true</pre>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">password</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">empty string</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">password for the user</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>Standard property. This
            property is case sensitive. Example below:</p>
<pre class="programlisting"> jdbc:hsqldb:file:enrolments;user=aUserName;password=3xLVz</pre>
<p>For
            compatibility with other engines, a non-standard form of
            specifying user and password is also supported. In this form, user
            name and password appear at the end of the URL string, prefixed
            respectively with the question mark and the
            ampersand:</p>
<pre class="programlisting"> jdbc:hsqldb:file:enrolments;create=false?user=aUserName&amp;password=3xLVz</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N15041"></a>
<p class="title">
<b>Table&nbsp;12.6.&nbsp;Closing old ResultSet when Statement is reused</b>
</p>
<div class="table-contents">
<table summary="Closing old ResultSet when Statement is reused" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="7cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">close_result</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">false</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">closing the old result set when a new ResultSet is created
            by a Statement</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>This property is used for
            compatibility with the JDBC specification. When true (the JDBC
            specification), a <code class="classname">ResultSet</code> that was
            previously returned by executing a
            <code class="classname">Statement</code> or
            <code class="classname">PreparedStatement</code> is closed as soon as the
            <code class="classname">Statement</code> is executed
            again.</p>
<p>The default is false as previous versions of
            HSQLDB did not close old result set. The user application should
            close old result sets when they are no longer needed and should
            not rely on auto-closing side effect of executing the
            Statement.</p>
<p>The default is false. When the property is
            true, the old <code class="classname">ResultSet</code> is closed when a
            <code class="classname">Statement</code> is re-executed. Example
            below:</p>
<pre class="programlisting"> jdbc:hsqldb:hsql://localhost/enrolments;close_result=true</pre>
<p>When
            a <code class="classname">ResultSet</code> is used inside a user-defined
            stored procedure, the default, false, is always used for this
            property.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N15088"></a>
<p class="title">
<b>Table&nbsp;12.7.&nbsp;Column Names in JDBC ResultSet</b>
</p>
<div class="table-contents">
<table summary="Column Names in JDBC ResultSet" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="7cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">get_column_name</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">true</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">column name in ResultSet</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>This property is used for
            compatibility with other JDBC driver implementations. When true
            (the default), <code class="methodname">ResultSet.getColumnName(int
            c)</code> returns the underlying column name. This property
            can be specified differently for different connections to the same
            database.</p>
<p>The default is true. When the property is
            false, the above method returns the same value as
            <code class="methodname">ResultSet.getColumnLabel(int column)</code>
            Example below:</p>
<pre class="programlisting"> jdbc:hsqldb:hsql://localhost/enrolments;get_column_name=false</pre>
<p>When
            a <code class="classname">ResultSet</code> is used inside a user-defined
            stored procedure, the default, true, is always used for this
            property.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N150C1"></a>
<p class="title">
<b>Table&nbsp;12.8.&nbsp;Creating New Database</b>
</p>
<div class="table-contents">
<table summary="Creating New Database" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">ifexists</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">false</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">connect only if database already exists</td>
</tr>
<tr>
<td style="border-bottom: 0.5pt solid ; " colspan="3" align="left" valign="top">
<p>Has an effect only with
            <em class="glossterm">mem:</em> and <em class="glossterm">file:</em>
            database. When true, will not create a new database if one does
            not already exist for the URL.</p>
<p>When the property is
            false (the default), a new <em class="glossterm">mem:</em> or
            <em class="glossterm">file:</em> database will be created if it does
            not exist.</p>
<p>Setting the property to true is useful when
            troubleshooting as no database is created if the URL is malformed.
            Example below:</p>
<pre class="programlisting"> jdbc:hsqldb:file:enrolments;ifexists=true</pre>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">create</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">true</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">create the database if it does not exist</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>Similar to the ifexists
            property, but with opposite meaning.</p>
<p>Has an effect
            only with <em class="glossterm">mem:</em> and
            <em class="glossterm">file:</em> database. When false, will not create
            a new database if one does not already exist for the
            URL.</p>
<p>When the property is true (the default), a new
            <em class="glossterm">mem:</em> or <em class="glossterm">file:</em>
            database will be created if it does not exist.</p>
<p>Setting
            the property to true is useful when troubleshooting as no database
            is created if the URL is malformed. Example
            below:</p>
<pre class="programlisting"> jdbc:hsqldb:file:enrolments;create=false</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N15120"></a>
<p class="title">
<b>Table&nbsp;12.9.&nbsp;Automatic Shutdown</b>
</p>
<div class="table-contents">
<table summary="Automatic Shutdown" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">shutdown</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">false</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">shut down the database when the last connection is
            closed</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>If this property is
            <code class="literal">true</code>, when the last connection to a database is
            closed, the database is automatically shut down. The property
            takes effect only when the first connection is made to the
            database. This means the connection that opens the database. It
            has no effect if used with subsequent
            connections.</p>
<p>This command has two uses. One is for
            test suites, where connections to the database are made from one
            JVM context, immediately followed by another context. The other
            use is for applications where it is not easy to configure the
            environment to shutdown the database. Examples reported by users
            include web application servers, where the closing of the last
            connection coincides with the web app being shut
            down.</p>
<pre class="programlisting"> jdbc:hsqldb:file:enrolments;shutdown=true</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<p>In addition, when the first connection to an
    <em class="glossterm">in-process</em> <code class="literal">file:</code> or
    <code class="literal">mem:</code> database creates a new database all the
    user-defined database properties can be specified as URL properties. See
    the next section for details.</p>
</div>
<div class="section" title="Database Properties in Connection URL and Properties">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="dpc_db_props_url"></a>Database Properties in Connection URL and Properties</h2>
</div>
</div>
</div>
<p>Each database has several default settings (properties) that are
    listed in the <a class="link" href="#management-chapt" title="Chapter&nbsp;11.&nbsp;System Management">System Management</a> chapter. These properties can be
    changed via SQL commands after a connection is made to the database. It is
    possible to specify most of these properties in the connection properties
    or as part of the URL string when the first connection is made to a new
    <code class="literal">file:</code> or <code class="literal">mem:</code> database. This allows
    the properties to be set without using any SQL commands. The corresponding
    SQL command is given for each property. For a server, these properties can
    be appended to the database path URL in server.properties or the server
    command line.</p>
<p>Note the prefered method of setting database properties is by using
    a set of SQL statements. These statements can be used both for a new
    database or an existing database, unlike URL properties that are generally
    effective for new databases only.</p>
<p>If the properties are used for connection to an existing database,
    they are ignored.</p>
<p>The exceptions are the following property settings that are allowed
    for the first connection to an existing database (the connection which
    reopens the database): <code class="literal">readonly=true</code>,
    <code class="literal">files_readonly=true</code>,
    <code class="literal">hsqldb.lock_file=false</code>,
    <code class="literal">hsqldb.sqllog=1-3</code>,
    <code class="literal">hsqldb.applog=1-3</code>. These specific property / value
    pairs override the existing database properties. For example a normal
    database is opened as readonly, or the lock file is not created, or the
    sql log level is set to a value between 1 and 3.</p>
<p>Management of properties has changed since version 1.8. The old SET
    PROPERTY statement does not change a property and is ignored. The
    statement is retained to simplify application upgrades.</p>
<p>In the example URL below, two properties are set for the first
    connection to a new database.</p>
<pre class="programlisting"> jdbc:hsqldb:file:enrolments;hsqldb.cache_rows=10000;hsqldb.nio_data_file=false</pre>
<p>In the table below, database properties that can be used as part of
    the URL or in connection properties are listed. For each property that can
    also be set with an SQL statement, the statement is also given. These
    statements are described more extensively in the <a class="link" href="#management-chapt" title="Chapter&nbsp;11.&nbsp;System Management">System Management</a>
    chapter.</p>
<div class="table">
<a name="N1518D"></a>
<p class="title">
<b>Table&nbsp;12.10.&nbsp;Validity Check Property</b>
</p>
<div class="table-contents">
<table summary="Validity Check Property" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">check_props</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">false</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">checks the validity of the connection properties</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>If the property is true,
            every database property that is specified on the URL or in
            connection properties is checked and if it is not used correctly,
            an error is returned.</p>
<pre class="programlisting">this property cannot be set with an SQL statement</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="section" title="SQL Conformance Properties">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dpc_sql_conformance"></a>SQL Conformance Properties</h3>
</div>
</div>
</div>
<div class="table">
<a name="N151BE"></a>
<p class="title">
<b>Table&nbsp;12.11.&nbsp;SQL Keyword Use as Identifier</b>
</p>
<div class="table-contents">
<table summary="SQL Keyword Use as Identifier" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">sql.enforce_names</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">false</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">enforcing SQL keywords</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>This property, when set
              true, prevents SQL keywords being used for database object names
              such as columns and tables.</p>
<pre class="programlisting">SET DATABASE SQL NAMES { TRUE | FALSE }</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N151EB"></a>
<p class="title">
<b>Table&nbsp;12.12.&nbsp;SQL Keyword Starting with the Underscore or Containing Dollar
        Characters</b>
</p>
<div class="table-contents">
<table summary="SQL Keyword Starting with the Underscore or Containing Dollar
        Characters" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">sql.regular_names</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">true</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">enforcing SQL keywords</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>This property, when set
              true, prevents database object names such as columns and tables
              beginning with the underscore or containing the dollar
              character.</p>
<pre class="programlisting">SET DATABASE SQL REGULAR NAMES { TRUE | FALSE }</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N15218"></a>
<p class="title">
<b>Table&nbsp;12.13.&nbsp;Reference to Columns Names</b>
</p>
<div class="table-contents">
<table summary="Reference to Columns Names" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">sql.enforce_refs</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">false</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">enforcing column reference disambiguation</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>This property, when set
              true, causes an error when an SQL statement (usually a select
              statement) contains column references that can be resolved by
              more than one table name or alias. In effect forces such column
              references to have a table name or table alias
              qualifier.</p>
<pre class="programlisting">SET DATABASE SQL REFERENCES { TRUE | FALSE }</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N15245"></a>
<p class="title">
<b>Table&nbsp;12.14.&nbsp;String Size Declaration</b>
</p>
<div class="table-contents">
<table summary="String Size Declaration" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">sql.enforce_size</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">true</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">size enforcement of string columns</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>Conforms to SQL standards
              for size and precision of data types. When true, all VARCHAR
              column type declarations require a size. When the property is
              false and there is no size in the declaration, a default size is
              used. Note that all other types accept a declaration without a
              size, which is interpreted as a default
              size.</p>
<pre class="programlisting">SET DATABASE SQL SIZE { TRUE | FALSE }</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N15272"></a>
<p class="title">
<b>Table&nbsp;12.15.&nbsp;Type Enforcement in Comparison and Assignment</b>
</p>
<div class="table-contents">
<table summary="Type Enforcement in Comparison and Assignment" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">sql.enforce_types</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">false</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">enforcing type compatibility</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>This property, when set
              true, causes an error when an SQL statements contains
              comparisons or assignments that are non-standard due to type
              mismatch. Most illegal comparisons and assignments will cause an
              exception regardless of this setting. This setting applies to a
              small number of comparisons and assignments that are possible,
              but not standard conformant, and were allowed in previous
              versions of HSQLDB.</p>
<pre class="programlisting">SET DATABASE SQL TYPES { TRUE | FALSE }</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N1529F"></a>
<p class="title">
<b>Table&nbsp;12.16.&nbsp;Foreign Key Triggered Data Change</b>
</p>
<div class="table-contents">
<table summary="Foreign Key Triggered Data Change" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">sql.enforce_tdc_delete</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">true</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">enforcing triggered data change violation for
              deletes</td>
</tr>
<tr>
<td style="border-bottom: 0.5pt solid ; " colspan="3" align="left" valign="top">
<p>The ON DELETE and ON
              UPDATE clauses of constraints cause data changes in rows in
              different tables or the same table. When there are multiple
              constraints, a row may be updated by one constraint and deleted
              by another constraint in the same operation. This is not allowed
              by default. Changing this property to false allows such
              violations of the Standard to pass without an exception. Used
              for porting from database engines that do not enforce the
              constraints.</p>
<pre class="programlisting">SET DATABASE SQL TDC DELETE { TRUE | FALSE }</pre>
</td>
</tr>
<tr>
<td style="border-bottom: 0.5pt solid ; " colspan="3" align="left" valign="top">&nbsp;</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">sql.enforce_tdc_update</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">true</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">enforcing triggered data change violation for
              updates</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>The ON DELETE and ON
              UPDATE clauses of foreign key constraints cause data changes in
              rows in different tables or the same table. With multiple
              constraint, a field may be updated by two constraints and set to
              different values. This is not allowed by default. Changing this
              property to false allows such violations of the Standard to pass
              without an exception. Used for porting from database engines
              that do not enforce the constraints
              properly.</p>
<pre class="programlisting">SET DATABASE SQL TDC UPDATE { TRUE | FALSE }</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N152E2"></a>
<p class="title">
<b>Table&nbsp;12.17.&nbsp;Use of LOB for LONGVAR Types</b>
</p>
<div class="table-contents">
<table summary="Use of LOB for LONGVAR Types" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">sql.longvar_is_lob</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">false</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">translating longvarchar and longvarbinary to lob</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>This property, when set
              true, causes type declarations using LONGVARCHAR and
              LONGVARBINARY to be translated to CLOB and BLOB respectively. By
              default, they are translated to VARCHAR and
              VARBINARY.</p>
<pre class="programlisting">SET DATABASE SQL LONGVAR IS LOB { TRUE | FALSE }</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N1530F"></a>
<p class="title">
<b>Table&nbsp;12.18.&nbsp;Concatenation with NULL</b>
</p>
<div class="table-contents">
<table summary="Concatenation with NULL" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">sql.concat_nulls</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">true</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">behaviour of concatenation involving one null</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>This property, when set
              false, causes the concatenation of a null and a not null value
              to return the not null value. By default, it returns
              null.</p>
<pre class="programlisting">SET DATABASE SQL CONCAT NULLS { TRUE | FALSE }</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N1533C"></a>
<p class="title">
<b>Table&nbsp;12.19.&nbsp;NULL in Multi-Column UNIQUE Constraints</b>
</p>
<div class="table-contents">
<table summary="NULL in Multi-Column UNIQUE Constraints" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">sql.unique_nulls</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">true</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">behaviour of multi-column UNIQUE constraints with null
              values</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>This property, when set
              false, causes multi-column unique constrains to be more
              restrictive for value sets that contain a mix of null and not
              null values.</p>
<pre class="programlisting">SET DATABASE SQL UNIQUE NULLS { TRUE | FALSE }</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N15369"></a>
<p class="title">
<b>Table&nbsp;12.20.&nbsp;Truncation or Rounding in Type Conversion</b>
</p>
<div class="table-contents">
<table summary="Truncation or Rounding in Type Conversion" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">sql.convert_trunc</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">true</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">behaviour of type conversion from DOUBLE to integral
              types</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>This property, when set
              false, causes type conversions from DOUBLE to any integral type
              to use rounding. By default truncation is
              used.</p>
<pre class="programlisting">SET DATABASE SQL CONVERT TRUNCATE { TRUE | FALSE }</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N15396"></a>
<p class="title">
<b>Table&nbsp;12.21.&nbsp;Decimal Scale of Division and AVG Values</b>
</p>
<div class="table-contents">
<table summary="Decimal Scale of Division and AVG Values" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">sql.avg_scale</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">0</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">decimal scale of values returned by division and the AVG
              and MEDIAN aggregate functions</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>By default, the result of
              a division or an AVG or MEDIAN aggregate has the same type and
              scale as the aggregated value. For INTEGER types, the scale is
              0. When this property is set to a value other than the default
              0, then the scale is used if it is greater than the scale of the
              divisor or aggregated value. This property does not affect
              DOUBLE values. Values between 0 - 10 can be used for this
              property.</p>
<pre class="programlisting">SET DATABASE SQL AVG SCALE &lt;numeric value&gt;</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N153C3"></a>
<p class="title">
<b>Table&nbsp;12.22.&nbsp;Support for NaN values</b>
</p>
<div class="table-contents">
<table summary="Support for NaN values" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">sql.double_nan</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">true</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">behaviour of expressions returning DOUBLE NaN</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>This property, when set
              false, causes division of DOUBLE values by Zero to return a
              Double.NaN value. By default an exception is
              thrown.</p>
<pre class="programlisting">SET DATABASE SQL DOUBLE NAN { TRUE | FALSE }</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N153F0"></a>
<p class="title">
<b>Table&nbsp;12.23.&nbsp;Sort order of NULL values</b>
</p>
<div class="table-contents">
<table summary="Sort order of NULL values" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">sql.nulls_first</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">true</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">ordering of NULL values</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>By default, nulls appear
              before not-null values when a result set is ordered without
              specifying NULLS FIRST or NULLS LAST. This property, when set
              false, causes nulls to appear by default after not-null values
              in result sets with ORDER BY</p>
<pre class="programlisting">SET DATABASE SQL NULLS FIRST { TRUE | FALSE }</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N1541D"></a>
<p class="title">
<b>Table&nbsp;12.24.&nbsp;Sort order of NULL values with DESC</b>
</p>
<div class="table-contents">
<table summary="Sort order of NULL values with DESC" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">sql.nulls_order</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">true</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">ordering of NULL values when DESC is used</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>By default, when an ORDER
              BY clause that does not specify NULLS FIRST or NULLS LAST is
              used, nulls are ordered according to the
              <code class="literal">sql.nulls_first</code> setting even when DESC is
              used after ORDER BY. This property, when set false, causes nulls
              to appear in the opposite position when DESC is
              used.</p>
<pre class="programlisting">SET DATABASE SQL NULLS ORDER { TRUE | FALSE }</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N1544D"></a>
<p class="title">
<b>Table&nbsp;12.25.&nbsp;String comparison with padding</b>
</p>
<div class="table-contents">
<table summary="String comparison with padding" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">sql.pad_space</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">true</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">ordering of strings with trailing spaces</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>By default, when two
              strings are compared, he shorter string is padded with spaces
              before comparison. When this property is set false, no padding
              takes place before comparison. Without padding, the shorter
              string is never equal to the longer one.</p>
<p>Before
              version 2.0, HSQLDB used NO PAD comparison. If you need the old
              behaviour, use this property when opening an older
              database.</p>
<pre class="programlisting">SET DEFAULT COLLATION &lt;collation name&gt; [ NO PAD | PAD SPACE ]</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N1547C"></a>
<p class="title">
<b>Table&nbsp;12.26.&nbsp;Case Insensitive Varchar columns</b>
</p>
<div class="table-contents">
<table summary="Case Insensitive Varchar columns" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">sql.ignore_case</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">false</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">case-insensitive VARCHAR</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>When this propery is set
              true, all VARCHAR declarations in CREATE TABLE and other
              statemenst are assigned an Upper Case Comparison collation,
              SQL_TEXT_UCC. This is designed for compatibility with some
              databases that use case-insensitive comparison. It is better to
              specify the collation selectively for specific columns that
              require it.</p>
<pre class="programlisting">SET DATABASE COLLATION SQL_TEXT_UCC</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N154A9"></a>
<p class="title">
<b>Table&nbsp;12.27.&nbsp;DB2 Style Syntax</b>
</p>
<div class="table-contents">
<table summary="DB2 Style Syntax" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">sql.syntax_db2</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">false</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">support for DB2 style syntax</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>This property, when set
              true, allows compatibility with some aspects of this dialect.
              </p>
<pre class="programlisting">SET DATABASE SQL SYNTAX DB2 { TRUE | FALSE }</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N154D5"></a>
<p class="title">
<b>Table&nbsp;12.28.&nbsp;MSSQL Style Syntax</b>
</p>
<div class="table-contents">
<table summary="MSSQL Style Syntax" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">sql.syntax_mss</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">false</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">support for MS SQL Server style syntax</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>This property, when set
              true, switches the arguments of the CONVERT function and also
              allow compatibility with some other aspects of this dialect.
              </p>
<pre class="programlisting">SET DATABASE SQL SYNTAX MSS { TRUE | FALSE }</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N15501"></a>
<p class="title">
<b>Table&nbsp;12.29.&nbsp;MySQL Style Syntax</b>
</p>
<div class="table-contents">
<table summary="MySQL Style Syntax" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">sql.syntax_mys</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">false</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">support for MySQL style syntax</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>This property, when set
              true, enables support for TEXT and AUTO_INCREMENT types and also
              allow compatibility with some other aspects of this
              dialect.</p>
<pre class="programlisting">SET DATABASE SQL SYNTAX MYS { TRUE | FALSE }</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N1552E"></a>
<p class="title">
<b>Table&nbsp;12.30.&nbsp;Oracle Style Syntax</b>
</p>
<div class="table-contents">
<table summary="Oracle Style Syntax" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">sql.syntax_ora</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">false</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">support for Oracle style syntax</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>This property, when set
              true, enables support for non-standard types. It also enables
              DUAL, ROWNUM, NEXTVAL and CURRVAL syntax and and also allow
              compatibility with some other aspects of this
              dialect.</p>
<pre class="programlisting">SET DATABASE SQL SYNTAX ORA { TRUE | FALSE }</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N1555B"></a>
<p class="title">
<b>Table&nbsp;12.31.&nbsp;PostgreSQL Style Syntax</b>
</p>
<div class="table-contents">
<table summary="PostgreSQL Style Syntax" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">sql.syntax_pgs</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">false</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">support for PostgreSQL style syntax</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>This property, when set
              true, enables support for TEXT and SERIAL types. It also enables
              NEXTVAL, CURRVAL and LASTVAL syntax and also allow compatibility
              with some other aspects of this dialect.</p>
<pre class="programlisting">SET DATABASE SQL SYNTAX PGS { TRUE | FALSE }</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
</div>
<div class="section" title="Database Operations Properties">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dpc_db_operations"></a>Database Operations Properties</h3>
</div>
</div>
</div>
<div class="table">
<a name="N1558B"></a>
<p class="title">
<b>Table&nbsp;12.32.&nbsp;Default Table Type</b>
</p>
<div class="table-contents">
<table summary="Default Table Type" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">hsqldb.default_table_type</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">memory</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">type of table created with unqualified CREATE
              TABLE</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>The CREATE TABLE command
              results in a MEMORY table by default. Setting the value
              <span class="emphasis"><em>cached</em></span> for this property will result in a
              cached table by default. The qualified forms such as CREATE
              MEMORY TABLE or CREATE CACHED TABLE are not affected at all by
              this property.</p>
<pre class="programlisting">SET DATABASE DEFAULT TABLE TYPE { CACHED | MEMORY }</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N155BB"></a>
<p class="title">
<b>Table&nbsp;12.33.&nbsp;Transaction Control Mode</b>
</p>
<div class="table-contents">
<table summary="Transaction Control Mode" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">hsqldb.tx</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">locks</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">database transaction control mode</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>Indicates the transaction
              control mode for the database. The values, locks, mvlocks and
              mvcc are allowed.</p>
<pre class="programlisting">SET DATABASE TRANSACTION CONTROL { LOCKS | MVLOCKS | MVCC }</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N155E8"></a>
<p class="title">
<b>Table&nbsp;12.34.&nbsp;Default Isolation Level for Sessions</b>
</p>
<div class="table-contents">
<table summary="Default Isolation Level for Sessions" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">hsqldb.tx_level</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">read_commited</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">database default transaction isolation level</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>Indicates the default
              transaction isolation level for each new session. The values,
              read_committed and serializable are allowed. Individual sessions
              can change their isolation level.</p>
<pre class="programlisting">SET DATABASE DEFAULT ISOLATION LEVEL { READ COMMITTED | SERIALIZABLE }</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N15615"></a>
<p class="title">
<b>Table&nbsp;12.35.&nbsp;Transaction Rollback in Deadlock</b>
</p>
<div class="table-contents">
<table summary="Transaction Rollback in Deadlock" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">hsqldb.tx_conflict_rollback</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">true</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">effect of deadlock or other conflicts on
              transaction</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>When a transaction
              deadlock or other unresolvable conflict is about to happen, the
              current transaction is rolled back and an exception is raised.
              When this property is set false, the transaction is not rolled
              back. Only the latest action that would cause the conflict is
              undone and an error is returned. The property should not be
              changed unless the application can quickly perform an
              alternative statement and complete the transaction. It is
              provided for compatibility with other database engines which do
              not roll back the transaction upon
              deadlock.</p>
<pre class="programlisting">SET DATABASE TRANSACTION ROLLBACK ON CONFLICT { TRUE | FALSE }</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N15642"></a>
<p class="title">
<b>Table&nbsp;12.36.&nbsp;Time Zone and Interval Types</b>
</p>
<div class="table-contents">
<table summary="Time Zone and Interval Types" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">hsqldb.translate_tti_types</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">true</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">usage of type codes for advanced datetime and interval
              types</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>If the property is true,
              the TIME / TIMESTAMP WITH TIME ZONE types and INTERVAL types are
              represented in JDBC methods of
              <code class="classname">ResultSetMetaData</code> and
              <code class="classname">DatabaseMetaData</code> as JDBC datetime types
              without time zone and the VARCHAR type respectively. The
              original type names are preserved.</p>
<pre class="programlisting">SET DATABASE SQL TRANSLATE TTI TYPES { TRUE | FALSE }</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
</div>
<div class="section" title="Database File and Memory Properties">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dpc_db_file_mem"></a>Database File and Memory Properties</h3>
</div>
</div>
</div>
<div class="table">
<a name="N15679"></a>
<p class="title">
<b>Table&nbsp;12.37.&nbsp;Opening Database as Read Only</b>
</p>
<div class="table-contents">
<table summary="Opening Database as Read Only" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">readonly</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">false</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">readonly database - is used to open an existing
              <code class="literal">file:</code> database</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>This property is a special
              property that can be added manually to the .properties file, or
              included in the URL or connection properties. When this property
              is true, the database becomes readonly. This can be used with an
              existing database to open it for readonly
              operation.</p>
<pre class="programlisting">this property cannot be set with an SQL statement - it can be used in the .properties file</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N156A9"></a>
<p class="title">
<b>Table&nbsp;12.38.&nbsp;Opening Database Without Modifying the Files</b>
</p>
<div class="table-contents">
<table summary="Opening Database Without Modifying the Files" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">files_readonly</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">false</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">readonly files database - is used to open an existing
              <code class="literal">file:</code> database</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>This property is used
              similarly to the hsqldb.readonly property. When this property is
              true, CACHED and TEXT tables are readonly but memory tables are
              not. Any change to the data is not persisted to database
              files.</p>
<pre class="programlisting">this property cannot be set with an SQL statement - it can be used in the .properties file</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N156D9"></a>
<p class="title">
<b>Table&nbsp;12.39.&nbsp;Huge database files and tables</b>
</p>
<div class="table-contents">
<table summary="Huge database files and tables" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">hsqldb.large_data</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">false</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">enable huge database files - can also be used to open an
              existing <code class="literal">file:</code> database</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>By default, up to 2
              billion rows can be stored in disk-based CACHED tables. Setting
              this property to true increases the limit to 256 billion rows.
              This property is used as a connection
              property.</p>
<pre class="programlisting">this property cannot be set with an SQL statement - it can be used as a connection property for the connection that opens the database</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N15709"></a>
<p class="title">
<b>Table&nbsp;12.40.&nbsp;Event Logging</b>
</p>
<div class="table-contents">
<table summary="Event Logging" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">hsqldb.applog</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">0</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">application logging level - can also be used when
              openning an existing <code class="literal">file:</code> database</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>The default level 0
              indicates no logging. Level 1 results in minimal logging,
              including any failures. Level 2 indicates all events, including
              ordinary events. LEVEL 3 adds details of some of the normal
              operations. The events are logged in a file ending with
              ".app.log".</p>
<pre class="programlisting">SET DATABASE EVENT LOG LEVEL { 0 | 1 | 2 | 3}</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N15739"></a>
<p class="title">
<b>Table&nbsp;12.41.&nbsp;SQL Logging</b>
</p>
<div class="table-contents">
<table summary="SQL Logging" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">hsqldb.sqllog</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">0</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">sql logging level - can also be used when openning an
              existing <code class="literal">file:</code> database</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>The default level 0
              indicates no logging. Level 1 logs only commits and rollbacks.
              Level 2 logs all the SQL statements executed, together with
              their parameter values. Long statements and parameter values are
              truncated. Level 3 is similar to Level 2 but does not truncate
              long statements and values. The events are logged in a file
              ending with ".sql.log". This property applies to existing file:
              databases as well as new databases.</p>
<pre class="programlisting">SET DATABASE EVENT LOG SQL LEVEL { 0 | 1 | 2 | 3}</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N15769"></a>
<p class="title">
<b>Table&nbsp;12.42.&nbsp;Temporary Result Rows in Memory</b>
</p>
<div class="table-contents">
<table summary="Temporary Result Rows in Memory" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">hsqldb.result_max_memory_rows</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">0</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">storage of temporary results and tables in memory or on
              disk</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>This property can be set
              to specify how many rows of each results or temporary table are
              stored in memory before the table is written to disk. The
              default is zero and means data is always stored in memory. If
              this setting is used, it should be set above
              1000.</p>
<pre class="programlisting">SET DATABASE DEFAULT RESULT MEMORY ROWS &lt;numeric value&gt;</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N15796"></a>
<p class="title">
<b>Table&nbsp;12.43.&nbsp;Rows Cached In Memory</b>
</p>
<div class="table-contents">
<table summary="Rows Cached In Memory" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">hsqldb.cache_free_count</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">512</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">maximum number of unused space recovery - can also be
              used when openning an existing <code class="literal">file:</code>
              database</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>The default indicates 512
              unused spaces are kept for later use. The value can range
              between 0 - 8096. </p>
<p>When rows are deleted, the space
              is recovered and kept for reuse for new rows. If too many rows
              are deleted, the smaller recovered spaces are lost and the
              largest ones are retained for later use. Normally there is no
              need to set this property.</p>
<pre class="programlisting">this property cannot be set with an SQL statement</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N157C8"></a>
<p class="title">
<b>Table&nbsp;12.44.&nbsp;Rows Cached In Memory</b>
</p>
<div class="table-contents">
<table summary="Rows Cached In Memory" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">hsqldb.cache_rows</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">50000</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">maximum number of rows in memory cache</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>Indicates the maximum
              number of rows of cached tables that are held in
              memory.</p>
<p>The value can range between 100- 4 billion.
              If the value is set via SET FILES CACHE ROWS then it becomes
              effective after the next database
              SHUTDOWN.</p>
<pre class="programlisting">SET FILES CACHE ROWS &lt;numeric value&gt;</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N157F7"></a>
<p class="title">
<b>Table&nbsp;12.45.&nbsp;Size of Rows Cached in Memory</b>
</p>
<div class="table-contents">
<table summary="Size of Rows Cached in Memory" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">hsqldb.cache_size</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">10000</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">memory cache size</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>Indicates the total size
              (in kilobytes) of rows in the memory cache used with cached
              tables. This size is calculated as the binary size of the rows,
              for example an INTEGER is 4 bytes. The actual memory size used
              by the objects is 2 to 4 times this value. This depends on the
              types of objects in database rows, for example with binary
              objects the factor is less than 2, with character strings, the
              factor is just over 2 and with date and timestamp objects the
              factor is over 3.</p>
<p>The value can range between 100 KB
              - 4 GB. The default is 10,000, representing 10,000 kilobytes. If
              the value is set via SET FILES then it becomes effective after
              the next database SHUTDOWN or
              CHECKPOINT.</p>
<pre class="programlisting">SET FILES CACHE SIZE &lt;numeric value&gt;</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N15826"></a>
<p class="title">
<b>Table&nbsp;12.46.&nbsp;Size Scale of Disk Table Storage</b>
</p>
<div class="table-contents">
<table summary="Size Scale of Disk Table Storage" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">hsqldb.cache_file_scale</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">32</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">unit used for storage of rows in the .data file</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>The default value
              corresponds to a maximum size of 64 GB for the .data file. This
              can be increased to 64, 128, 256, 512, or 1024 resulting in up
              to 2 TB GB storage. Settings below 32 in older databases are
              preserved until a SHUTDOWN COMPACT.</p>
<pre class="programlisting">SET FILES SCALE &lt;numeric value&gt;</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N15853"></a>
<p class="title">
<b>Table&nbsp;12.47.&nbsp;Size Scale of LOB Storage</b>
</p>
<div class="table-contents">
<table summary="Size Scale of LOB Storage" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">hsqldb.lob_file_scale</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">32</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">unit used for storage of lobs in the .lobs file</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>The default value
              represents units of 32KB. When the average size of individual
              lobs in the database is smaller, a smaller unit can be used to
              reduce the overall size of the .lobs file. Values 1, 2, 4, 8,
              16, 32 can be used.</p>
<pre class="programlisting">SET FILES LOB SCALE &lt;numeric value&gt;</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N15880"></a>
<p class="title">
<b>Table&nbsp;12.48.&nbsp;Compression of BLOB and CLOB data</b>
</p>
<div class="table-contents">
<table summary="Compression of BLOB and CLOB data" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">hsqldb.lob_compressed</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">false</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">use of compression for storage of blobs and clobs</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>The default value is
              false, indicating no compression. When the value is true at the
              time of creation of a new database, blobs and clobs are stored
              as compressed parts.</p>
<pre class="programlisting">SET FILES LOB COMPRESSED { TRUE | FALSE }</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N158AD"></a>
<p class="title">
<b>Table&nbsp;12.49.&nbsp;Internal Backup of Database Files</b>
</p>
<div class="table-contents">
<table summary="Internal Backup of Database Files" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">hsqldb.inc_backup</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">true</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">incremental backup of data file</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>During updates, the
              contents of the .data file are modified. When this property is
              true, the modified contents are backed up gradually. This causes
              a marginal slowdown in operations, but allows fast checkpoint
              and shutdown.</p>
<p>When the property is false, the .data
              file is backed up entirely at the time of checkpoint and
              shutdown. Up to version 1.8, HSQLDB supported only full
              backup.</p>
<pre class="programlisting">SET FILES BACKUP INCREMENT { TRUE | FALSE }</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N158DC"></a>
<p class="title">
<b>Table&nbsp;12.50.&nbsp;Use of Lock File</b>
</p>
<div class="table-contents">
<table summary="Use of Lock File" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">hsqldb.lock_file</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">true</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">use of lock file - can also be used with an existing
              <code class="literal">file:</code> database</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>By default, a lock file is
              created for each file database that is opened for read and
              write. This property can be specified with the value false to
              prevent the lock file from being created. This usage is not
              recommended but may be desirable when flash type storage is
              used. This property applies to existing file: databases as well
              as new databases.</p>
<pre class="programlisting">this property cannot be set with an SQL statement</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N1590C"></a>
<p class="title">
<b>Table&nbsp;12.51.&nbsp;Logging Data Change Statements</b>
</p>
<div class="table-contents">
<table summary="Logging Data Change Statements" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">hsqldb.log_data</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">true</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">logging data change</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>This property can be set
              to <code class="literal">false</code> when database recovery in the event
              of an unexpected crash is not necessary. A database that is used
              as a temporary cache is an example. Regardless of the value of
              this property, if there is a proper shutdown of the database,
              all the changed data is stored. A checkpoint or shutdown still
              rewrites the <code class="literal">.script</code> file and saves the
              <code class="literal">.backup</code> file according to the other
              settings.</p>
<pre class="programlisting">SET FILES LOG  { TRUE | FALSE }</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N15942"></a>
<p class="title">
<b>Table&nbsp;12.52.&nbsp;Automatic Checkpoint Frequency</b>
</p>
<div class="table-contents">
<table summary="Automatic Checkpoint Frequency" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">hsqldb.log_size</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">50</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">size of log when checkpoint is performed</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>The value is the size (in
              megabytes) that the <code class="literal">.log</code> file can reach
              before an automatic checkpoint occurs. A checkpoint rewrites the
              <code class="literal">.script</code> file and clears the
              <code class="literal">.log</code> file.</p>
<pre class="programlisting">SET FILES LOG SIZE &lt;numeric value&gt;</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N15978"></a>
<p class="title">
<b>Table&nbsp;12.53.&nbsp;Automatic Defrag at Checkpoint</b>
</p>
<div class="table-contents">
<table summary="Automatic Defrag at Checkpoint" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">hsqldb.defrag_limit</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">0</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">percentage of unused space causing a defrag at
              checkpoint</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>When a checkpoint is
              performed, the percentage of wasted space in the .data file is
              calculated. If the wasted space is above the specified limit, a
              defrag operation is performed. The default is 0, which means no
              automatic checkpoint. The numeric value must be between 0 and
              100 and is interpreted as a percentage of the current size of
              the .data file.</p>
<pre class="programlisting">SET FILES DEFRAG &lt;numeric value&gt;</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N159A5"></a>
<p class="title">
<b>Table&nbsp;12.54.&nbsp;Compression of the .script file</b>
</p>
<div class="table-contents">
<table summary="Compression of the .script file" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">hsqldb.script_format</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">0</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">compressed .script file</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>If the property is set
              with the value 3, the .script file is stored in compressed
              format. This is useful for large script files. The .script is no
              longer readable when the
              <code class="literal">hsqldb.script_format=3</code> has been
              used.</p>
<pre class="programlisting">This property cannot be set with an SQL statement</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N159D5"></a>
<p class="title">
<b>Table&nbsp;12.55.&nbsp;Logging Data Change Statements Frequency</b>
</p>
<div class="table-contents">
<table summary="Logging Data Change Statements Frequency" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">hsqldb.write_delay</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">true</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">write delay performing fsync of log file entries</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>If the property is true,
              the default WRITE DELAY property of the database is used, which
              is 500 milliseconds. If the property is false, the WRITE DELAY
              is set to 0 seconds. The log is written to file regardless of
              this property. The property controls the fsync that forces the
              written log to be persisted to disk. The SQL command for this
              property allows more precise control over the
              property.</p>
<pre class="programlisting">SET FILES WRITE DELAY {{ TRUE | FALSE } | &lt;seconds value&gt; | &lt;milliseconds value&gt; MILLIS</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N15A02"></a>
<p class="title">
<b>Table&nbsp;12.56.&nbsp;Logging Data Change Statements Frequency</b>
</p>
<div class="table-contents">
<table summary="Logging Data Change Statements Frequency" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">hsqldb.write_delay_millis</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">500</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">write delay for performing fsync of log file
              entries</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>If the property is used,
              the WRITE DELAY property of the database is set the given value
              in milliseconds. The property controls the fsync that forces the
              written log to be persisted to disk. The SQL command for this
              property allows the same level of control over the
              property.</p>
<pre class="programlisting">SET FILES WRITE DELAY {{ TRUE | FALSE } | &lt;seconds value&gt; | &lt;milliseconds value&gt; MILLIS</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N15A2F"></a>
<p class="title">
<b>Table&nbsp;12.57.&nbsp;Use of NIO for Disk Table Storage</b>
</p>
<div class="table-contents">
<table summary="Use of NIO for Disk Table Storage" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">hsqldb.nio_data_file</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">true</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">use of nio access methods for the .data file</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>Setting this property to
              <code class="literal">false</code> will avoid the use of nio access
              methods, resulting in somewhat reduced speed. If the data file
              is larger than hsqldb.nio_max_size (default 256MB) when it is
              first opened (or when its size is increased), nio access methods
              are not used. Also, if the file gets larger than the amount of
              available computer memory that needs to be allocated for nio
              access, non-nio access methods are
              used.</p>
<pre class="programlisting">SET FILES NIO { TRUE | FALSE }</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N15A5F"></a>
<p class="title">
<b>Table&nbsp;12.58.&nbsp;Use of NIO for Disk Table Storage</b>
</p>
<div class="table-contents">
<table summary="Use of NIO for Disk Table Storage" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">hsqldb.nio_max_size</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">256</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">nio buffer size limit</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>The maximum size of .data
              file in mega bytes that can use the nio access method. When the
              file gets larger than this limit, non-nio access methods are
              used. Values 64, 128, 256, 512, 1024, and larger multiples of
              512 can be used. The default is
              256MB.</p>
<pre class="programlisting">SET FILES NIO SIZE &lt;numeric value&gt;</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N15A8C"></a>
<p class="title">
<b>Table&nbsp;12.59.&nbsp;Recovery Log Processing</b>
</p>
<div class="table-contents">
<table summary="Recovery Log Processing" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">hsqldb.full_log_replay</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">false</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">recovery log processing</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>The .log file is processed
              during recovery after a forced shutdwon. Out of memory
              conditions always abort the startup. Any other exception stops
              the processing of the .log file and by default, continues the
              startup process. If this property is true, the startup process
              is stopped if any exception occurs. Exceptions are usually
              caused by incomplete lines of SQL statements near the end of the
              .log file, which were not fully synced to disk when an abnormal
              shutdown occurred.</p>
<pre class="programlisting">This property cannot be set with an SQL statement</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N15AB9"></a>
<p class="title">
<b>Table&nbsp;12.60.&nbsp;Default Properties for TEXT Tables</b>
</p>
<div class="table-contents">
<table summary="Default Properties for TEXT Tables" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">textdb.*</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">0</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">default properties for new text tables</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>Properties that override
              the database engine defaults for newly created text tables.
              Settings in the text table <code class="literal">SET &lt;tablename&gt; SOURCE
              &lt;source string&gt; </code>command override both the engine
              defaults and the database properties defaults. Individual
              <span class="property">textdb.*</span> properties are listed in the <a class="link" href="#texttables-chapt" title="Chapter&nbsp;5.&nbsp;Text Tables">Text Tables</a> chapter.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N15AED"></a>
<p class="title">
<b>Table&nbsp;12.61.&nbsp;Forcing Garbage Collection</b>
</p>
<div class="table-contents">
<table summary="Forcing Garbage Collection" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">runtime.gc_interval</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">0</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">forced garbage collection</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>This setting forces
              garbage collection each time a set number of result set row or
              cache row objects are created. The default, "0" means no garbage
              collection is forced by the
              program.</p>
<pre class="programlisting">SET DATABASE GC &lt;numeric value&gt;</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
</div>
<div class="section" title="Crypt Properties">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dpc_crypt_props"></a>Crypt Properties</h3>
</div>
</div>
</div>
<div class="table">
<a name="N15B1E"></a>
<p class="title">
<b>Table&nbsp;12.62.&nbsp;Crypt Property For LOBs</b>
</p>
<div class="table-contents">
<table summary="Crypt Property For LOBs" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">crypt_lobs</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">false</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">encryption of lobs</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>If the property is true,
              the contents of the .lobs file is encrypted as
              well.</p>
<pre class="programlisting">this property cannot be set with an SQL statement</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N15B4B"></a>
<p class="title">
<b>Table&nbsp;12.63.&nbsp;Cipher Key for Encrypted Database</b>
</p>
<div class="table-contents">
<table summary="Cipher Key for Encrypted Database" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">crypt_key</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">none</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">encryption</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>The cipher key for an
              encrypted database.</p>
<pre class="programlisting">this property cannot be set with an SQL statement</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N15B78"></a>
<p class="title">
<b>Table&nbsp;12.64.&nbsp;Crypt Provider Encrypted Database</b>
</p>
<div class="table-contents">
<table summary="Crypt Provider Encrypted Database" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">crypt_provider</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">none</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">encryption</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>The fully-qualified class
              name of the cryptography provider. This property is not used for
              the default security provider.</p>
<pre class="programlisting">this property cannot be set with an SQL statement</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N15BA5"></a>
<p class="title">
<b>Table&nbsp;12.65.&nbsp;Cipher Specification for Encrypted Database</b>
</p>
<div class="table-contents">
<table summary="Cipher Specification for Encrypted Database" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">crypt_type</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">none</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">encryption</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>The cipher
              specification.</p>
<pre class="programlisting">this property cannot be set with an SQL statement</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<p>When connecting to an <em class="glossterm">in-process</em> database
      creates a new database, or opens an existing database (i.e. it is the
      first connection made to the database by the application), all the
      user-defined database properties listed in this section can be specified
      as URL properties.</p>
<p>When HSQLDB is used with OpenOffice.org as an external
      database, the property "default_schema=true" must be set on the URL,
      otherwise the program will not operate correctly as it does with its
      built-in hsqldb instance.</p>
</div>
</div>
<div class="section" title="System Properties">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="dpc_system_props"></a>System Properties</h2>
</div>
</div>
</div>
<p>A few system properties are used by HyperSQL. These are set on the
    Java command line or by calling System.setProperty() from the user's
    program. They are not valid as URL or connection properties.</p>
<div class="table">
<a name="N15BDF"></a>
<p class="title">
<b>Table&nbsp;12.66.&nbsp;Logging Framework</b>
</p>
<div class="table-contents">
<table summary="Logging Framework" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">hsqldb.reconfig_logging</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">true</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">configuring the framework logging</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>Setting this system property
            false avoids reconfiguring the framework logging system such as
            Log4J or java.util.Logging. If the property does not exist or is
            true, reconfiguration takes place.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N15C09"></a>
<p class="title">
<b>Table&nbsp;12.67.&nbsp;Text Tables</b>
</p>
<div class="table-contents">
<table summary="Text Tables" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">textdb.allow_full_path</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">false</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">text table file locations</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>Setting this system property
            true allows text table sources and files to be opened on all
            available paths. It also allows pure mem: databases to open such
            files. By default, only the database directory and its
            subdirectories are allowed. See the Text Tables
            chapter.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<div class="table">
<a name="N15C33"></a>
<p class="title">
<b>Table&nbsp;12.68.&nbsp;Java Functions</b>
</p>
<div class="table-contents">
<table summary="Java Functions" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="6.5cm" align="left" class="c1">
<col width="1.5cm" align="left" class="c2">
<col align="left" class="c3">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">hsqldb.method_class_names</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">none</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">allowed Java classes</td>
</tr>
<tr>
<td style="" colspan="3" align="left" valign="top">
<p>This property needs to be
            set with the names (including wildcards) of Java classes that can
            be used for routines based on Java static methods. See the SQL
            Invoked Routines chapter.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
</div>
</div>
<div class="chapter" title="Chapter&nbsp;13.&nbsp;HyperSQL Network Listeners (Servers)">
<div class="titlepage">
<div>
<div>
<h2 class="title">
<a name="listeners-chapt"></a>Chapter&nbsp;13.&nbsp;HyperSQL Network Listeners
    (Servers)</h2>
</div>
<div>
<h3 class="subtitle">
<i>Server, WebServer, and Servlet</i>
</h3>
</div>
<div>
<div class="authorgroup">
<div class="author">
<h3 class="author">
<span class="firstname">Fred</span> <span class="surname">Toussi</span>
</h3>
<div class="affiliation">
<span class="orgname">The HSQL Development Group<br>
</span>
</div>
</div>
</div>
</div>
<div>
<p class="releaseinfo">$Revision: 5292 $</p>
</div>
<div>
<div class="legalnotice" title="Legal Notice">
<a name="N15C88"></a>
<p>Copyright 2002-2012 Fred Toussi. Permission is granted to
      distribute this document without any alteration under the terms of the
      HSQLDB license. Additional permission is granted to the HSQL Development
      Group to distribute this document with or without alterations under the
      terms of the HSQLDB license.</p>
</div>
</div>
<div>
<p class="pubdate">2014-02-13 18:21:41-0500</p>
</div>
</div>
</div>
<div class="toc">
<p>
<b>Table of Contents</b>
</p>
<dl>
<dt>
<span class="section"><a href="#lsc_listener_types">Listeners</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#lsc_hsql_server">HyperSQL Server</a></span>
</dt>
<dt>
<span class="section"><a href="#lsc_http_server">HyperSQL HTTP Server</a></span>
</dt>
<dt>
<span class="section"><a href="#lsc_servlet">HyperSQL HTTP Servlet</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#lsc_server_props">Server and Web Server Properties</a></span>
</dt>
<dt>
<span class="section"><a href="#lsc_app_start">Starting a Server from your Application</a></span>
</dt>
<dt>
<span class="section"><a href="#lsc_remote_open">Allowing a Connection to Open or Create a Database</a></span>
</dt>
<dt>
<span class="section"><a href="#lsc_db_props_startup">Specifying Database Properties at Server Start</a></span>
</dt>
<dt>
<span class="section"><a href="#lsc_tls">TLS Encryption</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#lsc_tls_rquirements">Requirements</a></span>
</dt>
<dt>
<span class="section"><a href="#lsc_ssl_connection">Encrypting your JDBC connection</a></span>
</dt>
<dt>
<span class="section"><a href="#lsc_privatekey">Making a Private-key Keystore</a></span>
</dt>
<dt>
<span class="section"><a href="#lsc_auto_server_unix">Automatic Server or WebServer startup on UNIX</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#lsc_acl">Network Access Control</a></span>
</dt>
</dl>
</div>
<div class="section" title="Listeners">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="lsc_listener_types"></a>Listeners</h2>
</div>
</div>
</div>
<p>As described in the <a class="link" href="#running-chapt" title="Chapter&nbsp;1.&nbsp;Running and Using HyperSQL">Running and Using HyperSQL</a> chapter, network listeners (servers)
    provide connectivity to catalogs from different JVM processes. The
    HyperSQL listeners support both ipv4 and ipv6 network
    addressing.</p>
<div class="section" title="HyperSQL Server">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="lsc_hsql_server"></a>HyperSQL Server</h3>
</div>
</div>
</div>
<p>This is the preferred way of running a database server and the
      fastest one. This mode uses the proprietary <em class="glossterm">hsql:</em>
      communications protocol. The following example of the command for
      starting the server starts the server with one (default) database with
      files named "mydb.*" and the public name (alias) of "xdb".</p>
<div class="informalexample">
<pre class="screen"> java -cp ../lib/hsqldb.jar org.hsqldb.server.Server --database.0 file:mydb --dbname.0 xdb</pre>
</div>
<p>Alternatively, a server.properties file can be used for passing
      the arguments to the server. This file must be located in the directory
      where the command is issued.</p>
<pre class="screen"> java -cp ../lib/hsqldb.jar org.hsqldb.server.Server</pre>
<p>Alternatively, you can specify the path of the server.properties
      file on the command line. In this case, the properties file can have any
      name or extension, but it should be a valid properties file.</p>
<pre class="screen"> java -cp ../lib/hsqldb.jar org.hsqldb.server.Server --props myserver.props</pre>
<p>Use the --help argument to see the list of available
      arguments.</p>
<pre class="screen"> java -cp ../lib/hsqldb.jar org.hsqldb.server.Server --help</pre>
<p>The contents of the server.properties file is described in the
      next section.</p>
</div>
<div class="section" title="HyperSQL HTTP Server">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="lsc_http_server"></a>HyperSQL HTTP Server</h3>
</div>
</div>
</div>
<p>This method of access is used when the computer hosting the
      database server is restricted to the HTTP protocol. The only reason for
      using this method of access is restrictions imposed by firewalls on the
      client or server machines and it should not be used where there are no
      such restrictions. The HyperSQL HTTP Server is a special web server that
      allows JDBC clients to connect via HTTP. The server can also act as a
      small general-purpose web server for static pages.</p>
<p>To run an HTTP server, replace the main class for the server in
      the example command line above with the following:</p>
<div class="informalexample">
<pre class="screen"> java -cp ../lib/hsqldb.jar org.hsqldb.server.WebServer</pre>
</div>
<p>The contents of the server.properties file is described in the
      next section.</p>
</div>
<div class="section" title="HyperSQL HTTP Servlet">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="lsc_servlet"></a>HyperSQL HTTP Servlet</h3>
</div>
</div>
</div>
<p>This method of access also uses the HTTP protocol. It is used when
      a separate servlet engine (or application server) such as Tomcat or
      Resin provides access to the database. The Servlet Mode cannot be
      started independently from the servlet engine. The
      <code class="filename">Servlet</code> class, in the HSQLDB jar, should be
      installed on the application server to provide the connection. The
      database is specified using an application server property. Refer to the
      source file <code class="filename"><a class="filename" href="#Servlet.java-link">
      src/org/hsqldb/server/Servlet.java</a></code> to see the details.</p>
<p>Both HTTP Server and Servlet modes can only be accessed using the
      JDBC driver at the client end. They do not provide a web front end to
      the database. The Servlet mode can serve only a single database.</p>
<p>Please note that you do not normally use this mode if you are
      using the database engine in an application server. In this situation,
      connections to a catalog are usually made
      <em class="glossterm">in-process</em>, or using an external HSQL Server
      instance.</p>
</div>
</div>
<div class="section" title="Server and Web Server Properties">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="lsc_server_props"></a>Server and Web Server Properties</h2>
</div>
</div>
</div>
<p>Properties files for running the servers are not created
    automatically. You should create your own files that contain
    <span class="property">server.property</span>=<code class="literal">value</code> pairs for
    each property. The <code class="filename">server.properties</code> or
    <code class="filename">webserver.properties</code> files must be located in the
    directory where the command to run the
    <code class="classname">org.hsqldb.server.Server</code> class is issued.</p>
<p>In all properties files, values are case-sensitive. All values apart
    from names of files or pages are required in lowercase (e.g.
    <span class="property">server.silent</span>=<code class="literal">FALSE</code> will have no
    effect, but <span class="property">server.silent</span>=<code class="literal">false</code>
    will work). Supported properties and their default values (if any) are as
    follows:</p>
<div class="table">
<a name="N15CF3"></a>
<p class="title">
<b>Table&nbsp;13.1.&nbsp;common server and webserver properties</b>
</p>
<div class="table-contents">
<table summary="common server and webserver properties" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="4cm" align="left">
<col width="4cm" align="left">
<col align="left">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Value</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">server.database.0</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">file:test</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">the catalog type, path and file name of the first database
            file to use</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">server.dbname.0</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">""</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">lowercase server alias for the first database file</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">server.database.n</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">NO DEFAULT</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">the catalog type, path and file name of the n'th database
            file in use</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">server.dbname.n</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">NO DEFAULT</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">lowercase server alias for the n'th database file</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">server.silent</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">true</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">no extensive messages displayed on console</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">server.trace</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">false</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">JDBC trace messages displayed on console</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">server.address</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">NO DEFAULT</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">IP address of server</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">server.tls</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">false</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">Whether to encrypt network stream. If this is set to
            <code class="literal">true</code>, then in normal situations you will also
            need to set properties
            <code class="varname">system.javax.net.ssl.keyStore</code> and
            <code class="varname">system.javax.net.ssl.keyStorePassword</code>, as
            documented elsewhere. The value of <code class="varname">server.tls</code>
            impacts the default value of
            <code class="varname">server.port</code>.</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">server.daemon</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">false</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">Whether the server is run as a daemon</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; " align="left" valign="top"><span class="property">server.remote_open</span></td><td style="border-right: 0.5pt solid ; " align="left" valign="top"><code class="literal">false</code></td><td style="" align="left" valign="top">Allows opening a database path remotely when the first
            connection is made</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<p>In HyperSQL version 2.0, each server can serve an unlimited number
    of databases simultaneously. The <span class="property">server.database.0</span>
    property defines the filename / path whereas the
    <span class="property">server.dbname.0</span> defines the lowercase alias used by
    clients to connect to that database. The digit 0 is incremented for the
    second database and so on. Values for the
    <span class="property">server.database.n</span> property can use the
    <em class="glossterm">mem:</em>, <em class="glossterm">file:</em> or
    <em class="glossterm">res:</em> prefixes and connection properties as
    discussed under CONNECTIONS. For example, </p>
<div class="informalexample">
<pre class="programlisting"> database.0=mem:temp;sql.enforce_strict_size=true;</pre>
</div>
<p>Properties or default values specific to
    <code class="filename">server.properties</code> are:</p>
<div class="table">
<a name="N15D90"></a>
<p class="title">
<b>Table&nbsp;13.2.&nbsp;server properties</b>
</p>
<div class="table-contents">
<table summary="server properties" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="4cm" align="left">
<col width="4cm" align="left">
<col align="left">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Value</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">server.port</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">9001 (normal) or 554 (if TLS
            encrypted)</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">TCP/IP port used for talking to clients. All databases are
            served on the same port.</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; " align="left" valign="top"><span class="property">server.no_system_exit</span></td><td style="border-right: 0.5pt solid ; " align="left" valign="top"><code class="literal">true</code></td><td style="" align="left" valign="top">no <code class="literal">System.exit()</code> call when the database
            is closed</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<p>Properties or default values specific to
    <code class="filename">webserver.properties</code> are:</p>
<div class="table">
<a name="N15DC2"></a>
<p class="title">
<b>Table&nbsp;13.3.&nbsp;webserver properties</b>
</p>
<div class="table-contents">
<table summary="webserver properties" cellspacing="0" width="100%" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col width="4cm" align="left">
<col width="4cm" align="left">
<col align="left">
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Value</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left">Default</th><th style="border-bottom: 0.5pt solid ; " align="left">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">server.port</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">80 (normal) or 443 (if TLS
            encrypted)</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">TCP/IP port used for talking to clients</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">server.default_page</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">index.html</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">the default web page for server</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><span class="property">server.root</span></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">./</code></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top">the location of served pages</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; " align="left" valign="top"><span class="property">.&lt;extension&gt;</span></td><td style="border-right: 0.5pt solid ; " align="left" valign="top"><code class="literal">NO DEFAULT</code></td><td style="" align="left" valign="top">multiple entries such as <code class="literal">.html=text/html</code>
            define the mime types of the static files served by the web
            server. See the source for <code class="filename"><a class="filename" href="#WebServer.java-link">
            src/org/hsqldb/server/WebServer.java</a></code> for a
            list.</td>
</tr>
</tbody>
</table>
</div>
</div>
<br class="table-break">
<p>An example of the contents of a
    <code class="filename">server.properties</code> file is given below:</p>
<pre class="programlisting"> server.database.0=file:/opt/db/accounts
 server.dbname.0=accounts

 server.database.1=file:/opt/db/mydb
 server.dbname.1=enrolments

 server.database.2=mem:adatabase
 server.dbname.2=quickdb</pre>
<p>In the above example, the <code class="filename">server.properties</code>
    file indicates that the server provides access to 3 different databases.
    Two of the databases are file-based, while the third is all-in-memory. The
    aliases for the databases that the users connect to are
    <code class="literal">accounts</code>, <code class="literal">enrolments</code> and
    <code class="literal">quickdb</code>.</p>
<p>All the above properties and their values can be specified on the
    command line to start the server by omitting the
    <code class="literal">server.</code> prefix. If a property/value pair is specified
    on the command line, it overrides the property value specified in the
    <code class="filename">server.properties</code> or
    <code class="filename">webserver.properties</code> file.</p>
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
<table border="0" summary="Note">
<tr>
<td valign="top" align="center" rowspan="2" width="25"><img alt="[Note]" src="../images/db/note.png"></td><th align="left">Note</th>
</tr>
<tr>
<td valign="top" align="left">
<p>Upgrading: If you have existing custom properties files, change
      the values to the new naming convention. Note the use of digits at the
      end of <span class="property">server.database.n</span> and
      <span class="property">server.dbname.n</span> properties.</p>
</td>
</tr>
</table>
</div>
</div>
<div class="section" title="Starting a Server from your Application">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="lsc_app_start"></a>Starting a Server from your Application</h2>
</div>
</div>
</div>
<p>If you want to start the server from within your application, as
    opposed to the command line or batch files, you should create an instance
    of Server or Web Server, then assign the properties and start the Server.
    An working example of this can be found in the <code class="classname"><a class="classname" href="#TestBase.java-link"> org.hsqldb.test.TestBase</a></code>
    source. The example below sets the same properties as in the
    server.properties file example.</p>
<pre class="programlisting"> HsqlProperties p = new HsqlProperties();
 p.setProperty("server.database.0","file:/opt/db/accounts");
 p.setProperty("server.dbname.0","an_alias");
 // set up the rest of properties

 // alternative to the above is
 Server server = new Server();
 server.setProperties(p);
 server.setLogWriter(null); // can use custom writer
 server.setErrWriter(null); // can use custom writer
 server.start();
</pre>
<p>The Server object has several alternative methods for setting
    databases and their public names. The server should be shutdown using the
    shutdown() method.</p>
</div>
<div class="section" title="Allowing a Connection to Open or Create a Database">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="lsc_remote_open"></a>Allowing a Connection to Open or Create a Database</h2>
</div>
</div>
</div>
<p>If the <code class="literal">server.remote_open</code> property is true, the
    Server works differently from the normal mode. In this mode, it is not
    necessary to have any databases listed as server.database.0 etc. in the
    Server startup properties. If there are databases listed, they are opened
    as normal. The server does not shutdown when the last database is
    closed.</p>
<p>In this mode, a connection can be established to a database that is
    not open or does not exist. The server will open the database or create
    it, then return a connection to the database.</p>
<p>The connection URL must include the path to the database, separated
    with a semicolon from the alias. In the example below, the database path
    specified as <code class="literal">file:C:/files/mydatabase</code> is opened and the
    database alias <code class="literal">xdb</code> is assigned to the database. After
    this, the next connection to the specified alias will connect to the same
    database. Any database path on the URL is ignored if the alias is serving
    a database.</p>
<p>The database path can point to a <code class="literal">file:</code> or
    <code class="literal">mem:</code> database.</p>
<p>If you use database properties on the URL, these properties are used
    when the new database is created. If no database properties are used on
    the URL, you can also specify the path with
    <code class="literal">filepath=&lt;path&gt;</code>. Examples below:</p>
<pre class="programlisting">Connection c = DriverManager.getConnection("jdbc:hsqldb:hsql://localhost/xdb;file:C:/files/mydatabase", "SA", "");
Connection c = DriverManager.getConnection("jdbc:hsqldb:hsql://localhost/xdb;mem:test;sql.enforce_types=true", "SA", "");
Connection c = DriverManager.getConnection("jdbc:hsqldb:hsql://localhost/xdb;filepath=file:C:/files/mydatabase", "SA", "");
</pre>
</div>
<div class="section" title="Specifying Database Properties at Server Start">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="lsc_db_props_startup"></a>Specifying Database Properties at Server Start</h2>
</div>
</div>
</div>
<p>Each database started by a Server has its own URL. When new
    databases are created by the server, the database properties for each of
    the new database can be appended to the database URL. Examples
    below:</p>
<pre class="programlisting">// example in server.propertie file
 server.database.0=file:/opt/db/accounts;hsqldb.default_table_type=cached;sql.enforce_names=true
 server.dbname.0=accounts

// example for setting the property programatically
 HsqlProperties p = new HsqlProperties();
 p.setProperty("server.database.0","file:/opt/db/accounts;hsqldb.default_table_type=cached;sql.enforce_names=true");
</pre>
<p>The specified properties apply only to a new database. They have no
    effect on an existing database apart from a few properties such as
    <code class="literal">readonly</code> listed in the <a class="link" href="#dbproperties-chapt" title="Chapter&nbsp;12.&nbsp;Properties">Properties</a>
    chapter.</p>
</div>
<div class="section" title="TLS Encryption">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="lsc_tls"></a>TLS Encryption</h2>
</div>
<div>
<h2 class="subtitle">Listener TLS Support (a. k. a. SSL)</h2>
</div>
<div>
<div class="authorgroup">
<div class="author">
<h3 class="author">
<span class="firstname">Blaine</span> <span class="surname">Simpson</span>
</h3>
<div class="affiliation">
<span class="orgname">The HSQL Development Group<br>
</span>
</div>
</div>
</div>
</div>
<div>
<p class="releaseinfo">$Revision: 5292 $</p>
</div>
<div>
<p class="pubdate">2014-02-13 18:21:41-0500</p>
</div>
</div>
</div>
<a name="N15E93" class="indexterm"></a>
<p>This section explains how to encrypt the stream between JDBC network
    clients and HyperSQL Listeners. If you are running an
    <em class="glossterm">in-process</em> (non-Listener) setup, this chapter does
    not apply to you.</p>
<div class="section" title="Requirements">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="lsc_tls_rquirements"></a>Requirements</h3>
</div>
</div>
</div>
<div class="itemizedlist" title="Hsqldb TLS Support Requirements">
<p class="title">
<b>Hsqldb TLS Support Requirements</b>
</p>
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>Java 4 and greater versions support JSSE.</p>
</li>
<li class="listitem">
<p>A <a class="link" href="#lsc_privatekey" title="Making a Private-key Keystore">JKS keystore containing a
          private key</a>, in order to run a Listener.</p>
</li>
<li class="listitem">
<p>If you are running the listener side, then you'll need to run
          a HSQLDB Server or WebServer Listener instance. It doesn't matter if
          the underlying database catalogs are new, and it doesn't matter if
          you are making a new Listener configuration or encrypting an
          existing Listener configuration. (You can turn encryption on and off
          at will).</p>
</li>
<li class="listitem">
<p>You need a HSQLDB jar file that was built with JSSE present.
          If you obtained your HSQLDB distribution from us, you are all set,
          because we build with Java 1.4 or later (which contains
          JSSE).</p>
</li>
</ul>
</div>
</div>
<div class="section" title="Encrypting your JDBC connection">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="lsc_ssl_connection"></a>Encrypting your JDBC connection</h3>
</div>
</div>
</div>
<p>At this time, only 1-way, server-cert encryption is tested.</p>
<div class="section" title="Client-Side">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="lsc_ssl_client"></a>Client-Side</h4>
</div>
</div>
</div>
<p>Just use one of the following protocol prefixes.</p>
<div class="itemizedlist" title="Hsqldb TLS URL Prefixes">
<p class="title">
<b>Hsqldb TLS URL Prefixes</b>
</p>
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>
<code class="literal">jdbc:hsqldb:hsqls://</code>
</p>
</li>
<li class="listitem">
<p>
<code class="literal">jdbc:hsqldb:https://</code>
</p>
</li>
</ul>
</div>
<p>The latter will only work for clients running with Java 1.4 or
        later.</p>
<p>If the listener you wish to connect to is using a certificate
        approved by your default trust keystore, then there is nothing else to
        do. If not, then you need to tell Java to "trust" the server cert.
        (It's a slight over-simplification to say that if the server
        certificate was purchased, then you are all set; if somebody "signed
        their own" certificate by self-signing or using a private ca
        certificate, then you need to set up trust).</p>
<p>First, you need to obtain the cert (only the "public" part of
        it). Since this cert is passed to all clients, you could obtain it by
        writing a Java client that dumps it to file, or perhaps by using
        <span class="emphasis"><em>openssl s_client</em></span>. Since in most cases, if you
        want to trust a non-commercial cert, you probably have access to the
        server keystore, I'll show an example of how to get what you need from
        the server-side JKS keystore.</p>
<p>You may already have an X509 cert for your server. If you have a
        server keystore, then you can generate a X509 cert like this. </p>
<div class="example">
<a name="N15ED4"></a>
<p class="title">
<b>Example&nbsp;13.1.&nbsp;Exporting certificate from the server's keystore</b>
</p>
<div class="example-contents">
<pre class="screen"> keytool -export -keystore server.store -alias existing_alias -file server.cer</pre>
</div>
</div>
<p>
<br class="example-break"> In this example, <code class="filename">server.cer</code> is the
        X509 certificate that you need for the next step.</p>
<p>Now, you need to add this cert to one of the system trust
        keystores or to a keystore of your own. See <a class="link" href="http://java.sun.com/javase/6/docs/technotes/guides/security/jsse/JSSERefGuide.html#CustomizingStores" target="_top">
        the Customizing Stores section in JSSERefGuide.html</a> to see
        where your system trust keystores are. You can put private keystores
        anywhere you want to. The following command will add the cert to an
        existing keystore, or create a new keystore if
        <code class="filename">client.store</code> doesn't exist.</p>
<div class="example">
<a name="N15EE6"></a>
<p class="title">
<b>Example&nbsp;13.2.&nbsp;Adding a certificate to the client keystore</b>
</p>
<div class="example-contents">
<pre class="screen"> keytool -import -trustcacerts -keystore trust.store -alias new_alias -file server.cer</pre>
</div>
</div>
<br class="example-break">
<p>If you are making a new keystore, you probably want to start
        with a copy of your system default keystore which you can find
        somewhere under your <code class="varname">JAVA_HOME</code> directory (typically
        <code class="filename">jre/lib/security/cacerts</code> for a JDK, but I forget
        exactly where it is for a JRE).</p>
<p>Unless your OS can't stop other people from writing to your
        files, you probably do not want to set a password on the trust
        keystore.</p>
<p>If you added the cert to a system trust store, then you are
        finished. Otherwise you will need to specify your custom trust
        keystore to your client program. The generic way to set the trust
        keystore is to set the system property
        <code class="classname">javax.net.ssl.trustStore</code> every time that you
        run your client program. For example </p>
<div class="example">
<a name="N15EFA"></a>
<p class="title">
<b>Example&nbsp;13.3.&nbsp;Specifying your own trust store to a JDBC client</b>
</p>
<div class="example-contents">
<pre class="screen"> java -Djavax.net.ssl.trustStore=/home/blaine/trust.store -jar /path/to/hsqldb.jar dest-urlid</pre>
</div>
</div>
<p>
<br class="example-break"> This example runs the program <a class="link" href="#unix-chapt" title="Chapter&nbsp;14.&nbsp;HyperSQL on UNIX">SqlTool</a>. SqlTool has built-in TLS
        support however, so, for SqlTool you can set
        <code class="varname">truststore</code> on a per-urlid basis in the SqlTool
        configuration file.</p>
<p>Note: The hostname in your database URL must match the
        <span class="emphasis"><em>Common Name</em></span> of the server's certificate exactly.
        That means that if a site certificate is <code class="literal">admc.com</code>,
        you can not use <code class="literal">jdbc:hsqldb:hsqls://localhost</code> or
        <code class="literal">jdbc:hsqldb:hsqls://www.admc.com:1100</code> to connect to
        it.</p>
<p>If you want more details on anything, see JSSERefGuide.html on
        <a class="link" href="http://java.sun.com/javase/6/docs/technotes/guides/security/jsse/JSSERefGuide.html" target="_top">
        Sun's site</a>, or in the subdirectory
        <code class="filename">docs/guide/security/jsse</code> of your Java SE
        docs.</p>
</div>
<div class="section" title="Server-Side (Listener-Side)">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="lsc_ssl_server"></a>Server-Side (Listener-Side)</h4>
</div>
</div>
</div>
<p>Get yourself a <a class="link" href="#lsc_privatekey" title="Making a Private-key Keystore"> JKS
        keystore containing a private key</a>. Then set properties
        <code class="varname">server.tls</code>,
        <code class="varname">system.javax.net.ssl.keyStore</code> and
        <code class="varname">system.javax.net.ssl.keyStorePassword</code> in your
        <code class="filename">server.properties</code> or
        <code class="filename">webserver.properties</code> file. Set
        <code class="varname">server.tls</code> to <code class="literal">true</code>,
        <code class="varname">system.javax.net.ssl.keyStore</code> to the path of the
        private key JKS keystore, and
        <code class="varname">system.javax.net.ssl.keyStorePassword</code> to the
        password (of both the keystore and the private key record-- they must
        be the same). If you specify relative file path values, they will be
        resolved relative to the <code class="varname">${user.dir}</code> when the JRE
        is started.</p>
<div class="caution" title="Caution" style="margin-left: 0.5in; margin-right: 0.5in;">
<table border="0" summary="Caution">
<tr>
<td valign="top" align="center" rowspan="2" width="25"><img alt="[Caution]" src="../images/db/caution.png"></td><th align="left"><a name="tlspassword-caution"></a>Caution</th>
</tr>
<tr>
<td valign="top" align="left">
<p>If you set any password in a .properties (or any other) file,
          you need to restrict access to the file. On a good operating system,
          you can do this like so: </p>
<div class="informalexample">
<pre class="screen"> chmod 600 path/to/server.properties</pre>
</div>
</td>
</tr>
</table>
</div>
<p>The values and behavior of the <code class="literal">system.*</code>
        settings above match the usage documented for
        <code class="varname">javax.net.ssl.keyStorePassword</code> and
        <code class="varname">javax.net.ssl.keyStore</code> in the JSSE docs.</p>
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
<table border="0" summary="Note">
<tr>
<td valign="top" align="center" rowspan="2" width="25"><img alt="[Note]" src="../images/db/note.png"></td><th align="left">Note</th>
</tr>
<tr>
<td valign="top" align="left">
<p>Before version 2.0, HyperSQL depended on directly setting
          the corresponding JSSE properties. The new idiom is more secure and
          easier to manage. If you have an old password in a UNIX init script
          config file, you should remove it.</p>
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="section" title="Making a Private-key Keystore">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="lsc_privatekey"></a>Making a Private-key Keystore</h3>
</div>
</div>
</div>
<p>There are two main ways to do this. Either you can use a
      certificate signed by a certificate authority, or you can make your own.
      One thing that you need to know in both cases is, the <span class="emphasis"><em>Common
      Name</em></span> of the cert has to be the exact hostname that JDBC
      clients will use in their database URL.</p>
<div class="section" title="CA-Signed Cert">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="lsc_ssl_certificate"></a>CA-Signed Cert</h4>
</div>
</div>
</div>
<p>I'm not going to tell you how to get a CA-signed SSL
        certificate. That is well documented at many other places.</p>
<p>Assuming that you have a standard pem-style private key
        certificate, here's how you can use <a class="link" href="http://www.openssl.org" target="_top">openssl</a> and the program
        <code class="classname">DERImport</code> to get it into a JKS keystore.</p>
<p>Because I have spent a lot of time on this document already, I
        am just giving you an example.</p>
<div class="example">
<a name="N15F75"></a>
<p class="title">
<b>Example&nbsp;13.4.&nbsp;Getting a pem-style private key into a JKS keystore</b>
</p>
<div class="example-contents">
<pre class="screen"> openssl pkcs8 -topk8 -outform DER -in Xpvk.pem -inform PEM -out Xpvk.pk8 -nocrypt

 openssl x509 -in Xcert.pem -out Xcert.der -outform DER

 java DERImport new.keystore NEWALIAS Xpvk.pk8 Xcert.der</pre>
</div>
</div>
<br class="example-break">
<div class="important" title="Important" style="margin-left: 0.5in; margin-right: 0.5in;">
<table border="0" summary="Important">
<tr>
<td valign="top" align="center" rowspan="2" width="25"><img alt="[Important]" src="../images/db/important.png"></td><th align="left">Important</th>
</tr>
<tr>
<td valign="top" align="left">
<p>Make sure to set the password of the key exactly the same as
          the password for the keystore!</p>
</td>
</tr>
</table>
</div>
<p>You need the program <code class="filename">DERImport.class</code> of
        course. Do some internet searches to find
        <code class="filename">DERImport.java</code> or
        <code class="filename">DERImport.class</code> and download it.</p>
<p>If DERImport has become difficult to obtain, I can write a
        program to do the same thing-- just let me know.</p>
</div>
<div class="section" title="Non-CA-Signed Cert">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="lsc_ssl_certificate_non_ca"></a>Non-CA-Signed Cert</h4>
</div>
</div>
</div>
<p>Run <code class="literal">man keytool</code> or see <a class="link" href="http://java.sun.com/javase/6/docs/technotes/guides/security/jsse/JSSERefGuide.html#CreateKeystore" target="_top">
        the Creating a Keystore section of JSSERefGuide.html</a>.</p>
</div>
</div>
<div class="section" title="Automatic Server or WebServer startup on UNIX">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="lsc_auto_server_unix"></a>Automatic Server or WebServer startup on UNIX</h3>
</div>
</div>
</div>
<p>If you are on UNIX and want to automatically start and stop a
      Server or WebServer running with encryption, set the
      <code class="varname">system.javax.net.ssl.keyStore</code> and
      <code class="varname">system.javax.net.ssl.keyStorePassword</code> properties as
      instructed above, and follow the instructions in the <a class="link" href="#unix-chapt" title="Chapter&nbsp;14.&nbsp;HyperSQL on UNIX">HyperSQL on UNIX</a> chapter, paying
      close attention to the TLS-related comments in the template config
      file.</p>
<p>If you are using a private server certificate, make sure to also
      set the trust store filepath for relevant urlids in your RC file, as
      explained in the sample <a class="link" href="#hsqldb.cfg-link">config
      file</a>.</p>
</div>
</div>
<div class="section" title="Network Access Control">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="lsc_acl"></a>Network Access Control</h2>
</div>
<div>
<h2 class="subtitle">(Server ACLs)</h2>
</div>
</div>
</div>
<a name="N15FB4" class="indexterm"></a><a name="N15FB7" class="indexterm"></a>
<p>JDBC connections will always be denied if the supplied user and
    password are not found in the target catalog. But an HyperSQL listener can
    also restrict access at the listener level, even protecting private
    catalogs which have insecure (or default) passwords. If you have an
    <em class="glossterm">in-process</em> setup, this section of the Guide doesn't
    apply to you.</p>
<p>Many (in fact, most) distributed database applications don't have
    application clients connect directly to the database, but instead
    encapsulate access in a controlling process. For example, a web app will
    usually access the data source on behalf of users, with end-user web
    browsers never accessing the database directly. In these cases and others,
    the security benefits of restricting listener access to specific source
    addresses is well worth the effort. ACLs work by restricting access
    according to the source address of the incoming connection request. This
    is efficient because the database engine never even gets the request until
    it is approved by the ACL filter code.</p>
<p>The sample file <code class="filename"><a class="filename" href="#acl.txt-link">sample/acl.txt</a></code> in your HyperSQL
    distribution explains how to write an ACL file. </p>
<pre class="programlisting"># $Id: acl.txt 826 2009-01-17 05:04:52Z unsaved $

# Sample HyperSQL Network Listener ACL file.
# Specify "allow" and "deny" rules
# For address specifications, individual addresses, host names, and
# network addresses with /bit suffix are allowed, but read the caveat about
# host names below, under the sample "localhost" rule.

# Blank lines ignored.
   # Lines with # as the first non-whitespace character are ignored.


allow 2001:db8::/32
# Allow this 32-bit ipv4 subnet

allow localhost
# You should use numerical addresses in ACL files, unless you are certain that
# the name will always be known to your network address resolution system
# (assume that you will lose Internet connectivity at some time).
# With a default name resolution setup on UNIX, you are safe to use names
# defined in your /etc/hosts file.

deny 192.168.101.253
# Deny a single IP address.
# In our example, 192.168.101.0/24 is our local, organizational network.
# 192.168.101.253 is the IP address of our Intern's PC.
# The Intern does not have permission to access our databases directly.

allow 192.168.101.0/24

# Any ipv4 or ipv6 candidate address not matched above will be denied
</pre>
<p>
    You put your file wherever it is convenient for you, and specify that path
    with the property <code class="varname">server.acl</code> or
    <code class="varname">webserver.acl</code> in your
    <code class="filename">server.properties</code> or
    <code class="filename">webserver.properties</code> file (depending on whether your
    listener instance is a <code class="classname">Server</code> or
    <code class="classname">WebServer</code>). You can specify the ACL file path with
    an absolute or relative path. If you use a relative path, it must be
    relative to the <code class="filename">.properties</code> file. It's often
    convenient to name the ACL file <code class="filename">acl.txt</code>, in the same
    directory as your <code class="filename">.properties</code> file and specify the
    property value as just <code class="filename">acl.txt</code>. This file name is
    intuitive, and things will continue to work as expected if you move or
    copy the entire directory.</p>
<div class="warning" title="Warning" style="margin-left: 0.5in; margin-right: 0.5in;">
<table border="0" summary="Warning">
<tr>
<td valign="top" align="center" rowspan="2" width="25"><img alt="[Warning]" src="../images/db/warning.png"></td><th align="left">Warning</th>
</tr>
<tr>
<td valign="top" align="left">
<p>If your <code class="classname">Server</code> or
      <code class="classname">WebServer</code> was started with a
      <code class="varname">*.acl</code> property, changes afterwards to the ACL file
      will be picked up immediately by your listener instance. You are advised
      to use the procedure below to prevent partial edits or mistakes from
      crippling your running server.</p>
</td>
</tr>
</table>
</div>
<p>When you edit your ACL file, it is both more convenient and more
    secure to test it as explained here before activating it. You could, of
    course, test an ACL file by editing it in-place, then trying to connect to
    your listener with JDBC clients from various source addresses. Besides
    being mightily laborious and boring, with this method it is very easy to
    accidentally open access to all source addresses or to deny access to all
    users until you fix incorrect ACL entries.</p>
<p>The suggested method of creating or changing ACLs is to work with an
    inactive file (for new ACL files, just don't enable the
    <code class="varname">*.acl</code> property yet; for changing an existing file, just
    copy it to a temporary file and edit the temporary file). Then use the
    <code class="classname">ServerAcl</code> class to test it. </p>
<div class="example">
<a name="N15FFE"></a>
<p class="title">
<b>Example&nbsp;13.5.&nbsp;Validating and Testing an ACL file</b>
</p>
<div class="example-contents">
<pre class="screen"> java -cp path/to/hsqldb.jar org.hsqldb.server.ServerAcl path/to/acl.txt</pre>
</div>
</div>
<p>
<br class="example-break"> If the specified ACL file fails validation, you will be given
    details about the problem. Otherwise, the validated rules will be
    displayed (including the implicit, default deny rules). You then type in
    host names and addresses, one-per-line. Each name or address is tested as
    if it were a HyperSQL network client address, using the same exact method
    that the HyperSQL listener will use. (HyperSQL listeners use this same
    <code class="classname">ServerAcl</code> class to test incoming source addresses).
    <code class="classname">ServerAcl</code> will report the rule which matches and
    whether access is denied or allowed to that address.</p>
<p>If you have edited a copy of an existing ACL file (as suggested
    above), then overwrite your live ACL file with your new, validated ACL
    file. I.e., copy your temp file over top of your live ACL file.</p>
<p>
<code class="classname">ServerAcl</code> can be run in the same exact way
    described above, to troubleshoot runtime access issues. If you use an ACL
    file and a user or application can't get a connection to the database, you
    can run <code class="classname">ServerAcl</code> to quickly and definitively find
    if the client is being prohibited by an ACL rule.</p>
</div>
</div>
<div class="chapter" title="Chapter&nbsp;14.&nbsp;HyperSQL on UNIX">
<div class="titlepage">
<div>
<div>
<h2 class="title">
<a name="unix-chapt"></a>Chapter&nbsp;14.&nbsp;HyperSQL on UNIX</h2>
</div>
<div>
<h3 class="subtitle">
<i>How to quickly get a HyperSQL (aka HSQLDB) Listener up and
    running on UNIX, including Mac OS X</i>
</h3>
</div>
<div>
<div class="author">
<h3 class="author">
<span class="firstname">Blaine</span> <span class="surname">Simpson</span>
</h3>
<div class="affiliation">
<span class="orgname">The HSQL Development Group<br>
</span>
</div>
</div>
</div>
<div>
<p class="releaseinfo">$Revision: 5212 $</p>
</div>
<div>
<p class="pubdate">2014-02-13 18:21:41-0500</p>
</div>
</div>
</div>
<div class="toc">
<p>
<b>Table of Contents</b>
</p>
<dl>
<dt>
<span class="section"><a href="#uxc_purpose">Purpose</a></span>
</dt>
<dt>
<span class="section"><a href="#uxc_install">Installation</a></span>
</dt>
<dt>
<span class="section"><a href="#uxc_cat_setup">Setting up Database Catalog and Listener</a></span>
</dt>
<dt>
<span class="section"><a href="#uxc_access">Accessing your Database</a></span>
</dt>
<dt>
<span class="section"><a href="#uxc_addl_accts">Create additional Accounts</a></span>
</dt>
<dt>
<span class="section"><a href="#uxc_shutdown">Shutdown</a></span>
</dt>
<dt>
<span class="section"><a href="#uxc_daemon">Running Hsqldb as a System Daemon</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#uxc_init_script_portability">Portability of <code class="filename">hsqldb</code> init script</a></span>
</dt>
<dt>
<span class="section"><a href="#uxc_init_script_setup">Init script Setup Procedure</a></span>
</dt>
<dt>
<span class="section"><a href="#uxc_inittrouble">Troubleshooting the Init
      Script</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#uxc_upgrade">Upgrading</a></span>
</dt>
</dl>
</div>
<div class="section" title="Purpose">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="uxc_purpose"></a>Purpose</h2>
</div>
</div>
</div>
<p>This chapter explains how to quickly install, run, and use a
    HyperSQL Listener (aka Server) on UNIX.</p>
<p>Note that, unlike a traditional database server, there are many
    use cases where it makes sense to run HyperSQL without any listener. This
    type of setup is called <em class="glossterm">in-process</em>, and is not
    covered here, since there is no UNIX-specific setup in that
    case.</p>
<p>I intend to cover what I think is the most common UNIX setup: To
    run a multi-user, externally-accessible catalog with permanent data
    persistence. (By the latter I mean that data is stored to disk so that the
    catalog data will persist across process shutdowns and startups). I also
    cover how to run the Listener as a system daemon.</p>
<p>When I give sample shell commands below, I use commands which
    will work in Bourne-compatible shells, including Bash and Korn. Users who
    insist on using the inferior C-shells will need to convert.</p>
</div>
<div class="section" title="Installation">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="uxc_install"></a>Installation</h2>
</div>
</div>
</div>
<p>Go to <a class="link" href="http://sourceforge.net/projects/hsqldb" target="_top">http://sourceforge.net/projects/hsqldb</a> and click on
    the "files" link. You want the current version. I can't be more specific
    because SourceForge/Geeknet are likely to continue changing their
    interface. See if there's a distribution for the current HSQLDB version in
    the format that you want.</p>
<p>If you want a binary package and we either don't provide it, or
    you prefer somebody else's build, you should still find out the current
    version of HyperSQL available at SourceForge. It's very likely that you
    can find a binary package for your UNIX variant with your OS distributor,
    <a class="link" href="http://www.jpackage.org/" target="_top">http://www.jpackage.org/</a>, <a class="link" href="http://sunfreeware.com/" target="_top">http://sunfreeware.com/</a>, etc. Nowadays, most UNIXes
    have software package management systems which check Internet
    repositories. Just search the repositories for "hsqldb" and "hypersql".
    The challenge is to find an <span class="emphasis"><em>up-to-date</em></span> package. You
    will get better features and support if you work with the current stable
    release of HyperSQL. (In particular, HyperSQL version 2.0.0 added tons of
    new features). Pay attention to what JVM versions your binary package
    supports. Our builds (version 2.0 and later) document the Java version it
    was built with in the file <code class="filename">doc/index.html</code>, but you
    can't depend on this if somebody else assembled your distribution. Java
    jar files are generally compatible with the same or greater major
    versions. For example,if your <code class="filename">hsqldb.jar</code> was built
    with Java 1.3.6-11, then it is compatible with Java versions 1.3.* and
    greater.</p>
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
<table border="0" summary="Note">
<tr>
<td valign="top" align="center" rowspan="2" width="25"><img alt="[Note]" src="../images/db/note.png"></td><th align="left">Note</th>
</tr>
<tr>
<td valign="top" align="left">
<p>It could very well happen that some of the file formats which I
      discuss below are not in fact offered. If so, then we have not gotten
      around to building them.</p>
</td>
</tr>
</table>
</div>
<p>Binary installation depends on the package format that you
    downloaded.</p>
<div class="variablelist">
<table border="0">
<col valign="top" align="left">
<tbody>
<tr>
<td>
<p>
<span class="term">Installing from a .pkg.Z file</span>
</p>
</td><td>
<p>This package is only for use by a Solaris super-user. It's a
          System V package. Download then uncompress the package with
          uncompress or gunzip </p>
<div class="informalexample">
<pre class="screen"> uncompress filename.pkg.Z</pre>
</div>
<p> You can read about the package by running
          </p>
<div class="informalexample">
<pre class="screen"> pkginfo -l -d filename.pkg</pre>
</div>
<p> Run pkgadd as root to install.</p>
<div class="informalexample">
<pre class="screen"> pkgadd -d filename.pkg</pre>
</div>
</td>
</tr>
<tr>
<td>
<p>
<span class="term">Installing from a BSD Port or Package</span>
</p>
</td><td>You're on your own. I find everything much easier when I
          install software to BSD without their package management
          systems.</td>
</tr>
<tr>
<td>
<p>
<span class="term">Installing from a .rpm file</span>
</p>
</td><td>
<p>Just skip this section if you know how to install an RPM. If
          you found the RPM using a software management system, then just have
          it install it. The remainder of item explains a generic command-line
          method which should work with any Linux variant. After you download
          the rpm, you can read about it by running </p>
<div class="informalexample">
<pre class="screen"> rpm -qip /path/to/file.rpm</pre>
</div>
<p>Rpms can be installed or upgraded by running </p>
<div class="informalexample">
<pre class="screen"> rpm -Uvh /path/to/file.rpm</pre>
</div>
<p> as root. Suse users may want to keep Yast aware
          of installed packages by running rpm through Yast: <code class="literal">yast2 -i
          /path/to/file.rpm</code>.</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="term">Installing from a .zip file</span>
</p>
</td><td>
<p class="simpara">Extract the zip file in an ancestor directory of the new
          HSQLDB home. You don't need to create the
          <code class="varname">HSQLDB_HOME</code> directory because the extraction will
          create a version-labelled directory, and the subdirectory "hsqldb".
          This "hsqldb" directory is your <code class="varname">HSQLDB_HOME</code>, and
          you can move it to wherever you wish. If you will be upgrading or
          maintaining multiple versions of HyperSQL, you will want to retain
          the version number in the directory tree somehow.</p>
<div class="informalexample">
<pre class="screen"> cd ancestor/of/new/hsqldb/home
 unzip /path/to/file.zip</pre>
</div>
<p class="simpara">All the files in the zip archive will be extracted to
          underneath a new subdirectory named like
          <code class="filename">hsqldb-2.0.2a/hsqldb</code>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<p>Take a look at the files you installed. (Under
    <code class="filename">hsqldb</code> for zip file installations. Otherwise, use the
    utilities for your packaging system). The most important file of the
    HyperSQL system is <code class="filename">hsqldb.jar</code>, which resides in the
    subdirectory <code class="filename">lib</code>. Depending on who built your
    distribution, your file name may have a version label in it, like
    <code class="filename">hsqldb-1.2.3.4.jar</code>.</p>
<div class="important" title="Important" style="margin-left: 0.5in; margin-right: 0.5in;">
<table border="0" summary="Important">
<tr>
<td valign="top" align="center" rowspan="2" width="25"><img alt="[Important]" src="../images/db/important.png"></td><th align="left">Important</th>
</tr>
<tr>
<td valign="top" align="left">
<p>For the purposes of this chapter, I define
      <code class="varname">HSQLDB_HOME</code> to be the parent directory of the lib
      directory that contains <code class="filename">hsqldb.jar</code>. E.g., if your
      path to <code class="filename">hsqldb.jar</code> is
      <code class="filename">/a/b/hsqldb/lib/hsqldb.jar</code>, then your
      <code class="varname">HSQLDB_HOME</code> is
      <code class="filename">/a/b/hsqldb</code>.</p>
<p>Furthermore, unless I state otherwise, all local file paths
      that I give are relative to the
      <code class="varname">HSQLDB_HOME</code>.</p>
</td>
</tr>
</table>
</div>
<p>If the description of your distribution says that the
    <code class="filename">hsqldb.jar</code> file will work for your Java version, then
    you are finished with installation. Otherwise you need to build a new
    <code class="filename">hsqldb.jar</code> file.</p>
<p>If you followed the instructions above and you still don't know
    what Java version your <code class="filename">hsqldb.jar</code> supports, then try
    reading documentation files like <code class="filename">readme.txt</code>,
    <code class="filename">README.TXT</code>, <code class="filename">INSTALL.txt</code> etc. (As
    I said above, our newer distributions always document the Java version for
    the build, in the file <code class="filename">doc/index.html</code>). If that still
    doesn't help, then you can just try your <code class="filename">hsqldb.jar</code>
    and see if it works, or build your own.</p>
<p>To use the supplied <code class="filename">hsqldb.jar</code>, just skip to
    the <a class="link" href="#uxc_cat_setup" title="Setting up a HyperSQL Persistent Database Catalog and a HyperSQL Network Listener"> next section of this
    document</a>. Otherwise build a new
    <code class="filename">hsqldb.jar</code>.</p>
<div class="procedure" title="Procedure&nbsp;14.1.&nbsp;Building hsqldb.jar">
<a name="N160FB"></a>
<p class="title">
<b>Procedure&nbsp;14.1.&nbsp;Building hsqldb.jar</b>
</p>
<ol class="procedure" type="1">
<li class="step" title="Step 1">
<p>If you don't already have Ant, download the latest stable binary
        version from <a class="link" href="http://ant.apache.org" target="_top">http://ant.apache.org</a>. cd to
        where you want Ant to live, and extract from the archive with
        </p>
<div class="informalexample">
<pre class="screen"> unzip /path/to/file.zip</pre>
</div>
<p>or</p>
<div class="informalexample">
<pre class="screen"> tar -xzf /path/to/file.tar.gz</pre>
</div>
<p>or</p>
<div class="informalexample">
<pre class="screen"> bunzip2 -c /path/to/file.tar.bz2 | tar -xzf -</pre>
</div>
<p> Everything will be installed into a new
        subdirectory named <code class="filename">apache-ant- + version</code>. You can
        rename the directory after the extraction if you wish.</p>
</li>
<li class="step" title="Step 2">
<p>Set the environmental variable <code class="varname">JAVA_HOME</code> to
        the base directory of your Java JRE or SDK, like </p>
<div class="informalexample">
<pre class="screen"> export JAVA_HOME; JAVA_HOME=/usr/java/j2sdk1.4.0</pre>
</div>
<p> The location is entirely dependent upon your
        variety of UNIX. Sun's rpm distributions of Java normally install to
        <code class="filename">/usr/java/something</code>. Sun's System V package
        distributions of Java (including those that come with Solaris)
        normally install to <code class="filename">/usr/something</code>, with a
        sym-link from <code class="filename">/usr/java</code> to the default version
        (so for Solaris you will usually set JAVA_HOME to
        <code class="filename">/usr/java</code>).</p>
</li>
<li class="step" title="Step 3">
<p>Remove the existing file <code class="varname">HSQLDB_HOME</code>
        <code class="filename">/lib/hsqldb.jar</code>.</p>
</li>
<li class="step" title="Step 4">
<p>cd to <code class="varname">HSQLDB_HOME</code><code class="filename">/build</code>.
        Make sure that the bin directory under your Ant home is in your search
        path. Run the following command. </p>
<div class="informalexample">
<pre class="screen"> ant hsqldb</pre>
</div>
<p> This will build a new
        <code class="varname">HSQLDB_HOME</code><code class="filename">/lib/hsqldb.jar</code>.</p>
</li>
</ol>
</div>
<p>See the <a class="link" href="#building-app" title="Appendix&nbsp;B.&nbsp;Building HyperSQL Jars">Building HyperSQL Jars</a> appendix if you want to build anything
    other than <code class="filename">hsqldb.jar</code> with all default
    settings.</p>
</div>
<div class="section" title="Setting up a HyperSQL Persistent Database Catalog and a HyperSQL Network Listener">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="uxc_cat_setup"></a>Setting up a HyperSQL Persistent Database Catalog and a HyperSQL
    Network Listener</h2>
</div>
</div>
</div>
<p>If you installed from an OS-specific package, you may already
    have a catalog and listener pre-configured. See if your package includes a
    file named <code class="filename">server.properties</code> (make use of your
    packaging utilities). If you do, then I suggest that you still read this
    section while you poke around, in order to understand your
    setup.</p>
<div class="procedure">
<ol class="procedure" type="1">
<li class="step" title="Step 1">
<p>Select a UNIX user to run the database process (JVM) as. If
        this database is for the use of multiple users, or is a production
        system (or to emulate a production system), you should dedicate a UNIX
        user for this purpose. In my examples, I use the user name
        <code class="literal">hsqldb</code>. In this chapter, I refer to this user as
        the <code class="varname">HSQLDB_OWNER</code>, since that user will own the
        database catalog files and the JVM processes.</p>
<p>If the account doesn't exist, then create it. On all system-5
        UNIXes and most hybrids (including Linux), you can run (as root)
        something like </p>
<div class="informalexample">
<pre class="screen"> useradd -c 'HSQLDB Database Owner' -s /bin/bash -m hsqldb</pre>
</div>
<p> (BSD-variant users can use a similar <code class="literal">pw
        useradd hsqldb...</code> command).</p>
</li>
<li class="step" title="Step 2">
<p>Become the <code class="varname">HSQLDB_OWNER</code>. Copy the sample
        file <code class="filename"><a class="filename" href="#server.properties-link">
        sample/server.properties</a></code> to the
        <code class="varname">HSQLDB_OWNER</code>'s home directory and rename it to
        <code class="filename">server.properties</code>. (As a final reminder,
        "sampleserver.properties" is a relative path, so it is understood to
        be relative to your <code class="varname">HSQLDB_HOME</code>).</p>
<pre class="programlisting"># Hsqldb Server cfg file.
# See the HyperSQL Network Listeners chapter of the HyperSQL User Guide.

# Each server.database.X setting defines a database "catalog".
# I.e., an independent set of data.
# Each server.database.X setting corresponds exactly to the jdbc:hsqldb:*
# JDBC URL you would use if you wanted to get a direct (In-Process)
# Connection to the catalog instead of "serving" it.

server.database.0=file:db0/db0
# I suggest that, for every file: catalog you define, you add the
# connection property "ifexists=true" after the database instance
# is created (which happens simply by starting the Server one time).
# Just append ";ifexists=true" to the file: URL, like so:
# server.database.0=file:db0/db0;ifexists=true

# server.dbname.0 defaults to "" (i.e. server.dbname.n for n==0), but
# the catalog definition n will be entirely ignored for n &gt; 0 if you do not
# set server.dbname.n.  I.e. dbname setting is required for n &gt; 0, though it
# may be set to blank (e.g. "server.dbname.3=")
</pre>
<p>Since the value of the first database
        (<span class="property">server.database.0</span>) begins with
        <em class="glossterm">file:</em>, the catalog will be persisted to a set
        of files in the specified directory with names beginning with the
        specified name. Set the path to whatever you want (relative paths will
        be relative to the directory containing the properties file). You can
        read about how to specify other catalogs of various types, and how to
        make settings for the listen port and many other things in other
        chapters of this guide.</p>
</li>
<li class="step" title="Step 3">
<p>Set and export the environmental variable
        <code class="varname">CLASSPATH</code> to the value of
        <code class="varname">HSQLDB_HOME</code> (as described above) plus
        "/lib/hsqldb.jar", like </p>
<div class="informalexample">
<pre class="screen"> export CLASSPATH; CLASSPATH=/path/to/hsqldb/lib/hsqldb.jar</pre>
</div>
<p> In <code class="varname">HSQLDB_OWNER</code>'s home
        directory, run</p>
<div class="informalexample">
<pre class="screen"> nohup java org.hsqldb.server.Server &amp;</pre>
</div>
<p>This will start the Listener process in the background, and
        will create your new database catalog "db0". Continue on when you see
        the message containing <code class="literal">HSQLDB server... is online</code>.
        <code class="literal">nohup</code> just makes sure that the command will not
        quit when you exit the current shell (omit it if that's what you want
        to do).</p>
</li>
</ol>
</div>
</div>
<div class="section" title="Accessing your Database">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="uxc_access"></a>Accessing your Database</h2>
</div>
</div>
</div>
<p>We're going to use SqlTool to access the database, so you will
    need the file <code class="filename">sqltool.jar</code> in addition to
    <code class="filename">hsqldb.jar</code>. If <code class="filename">sqltool.jar</code> isn't
    already sitting there beside <code class="filename">hsqldb.jar</code> (they both
    come pre-built), build it exactly as you would build
    <code class="filename">hsqldb.jar</code>, except use ant target
    <code class="literal">sqltool</code>. If your distribution came with a sqltool jar
    file with a version label, like <code class="filename">sqltool-1.2.3.4.jar</code>,
    that's fine-- use that file whenever I say
    <code class="filename">sqltool.jar</code> below.</p>
<p>Copy the file <code class="filename"><a class="filename" href="#sqltool.rc-link">sample/sqltool.rc</a></code> to the
    <code class="varname">HSQLDB_OWNER</code>'s home directory. Use
    <code class="literal">chmod</code> to make the file readable and writable only to
    <code class="varname">HSQLDB_OWNER</code>.</p>
<pre class="programlisting"># $Id: sqltool.rc 5288 2013-09-29 18:35:42Z unsaved $

# This is a sample RC configuration file used by SqlTool, DatabaseManager,
# and any other program that uses the org.hsqldb.lib.RCData class.
# See the documentation for SqlTool for various ways to use this file.

# If you have the least concerns about security, then secure access to
# your RC file.

# You can run SqlTool right now by copying this file to your home directory
# and running
#    java -jar /path/to/sqltool.jar mem
# This will access the first urlid definition below in order to use a 
# personal Memory-Only database.
# "url" values may, of course, contain JDBC connection properties, delimited
# with semicolons.
# As of revision 3347 of SqlFile, you can also connect to datasources defined
# here from within an SqlTool session/file with the command "\j urlid".

# You can use Java system property values in this file like this:  ${user.home}

# The only feature added recently is the optional "transiso" setting,
# which may be set to an all-caps transaction isolation level as listed
# in the Java API Spec for java.sql.Connection.
# Windows users are advised to use forward slashes instead of reverse slashes,
# and to avoid paths containing spaces or other funny characters.  (This
# recommendation applies to any Java app, not just SqlTool).

# A personal Memory-Only (non-persistent) database.
urlid mem
url jdbc:hsqldb:mem:memdbid
username SA
password

# A personal, local, persistent database.
urlid personal
url jdbc:hsqldb:file:${user.home}/db/personal;shutdown=true
username SA
password
transiso TRANSACTION_READ_COMMITTED
# When connecting directly to a file database like this, you should 
# use the shutdown connection property like this to shut down the DB
# properly when you exit the JVM.

# This is for a hsqldb Server running with default settings on your local
# computer (and for which you have not changed the password for "SA").
urlid localhost-sa
url jdbc:hsqldb:hsql://localhost
username SA
password



# Template for a urlid for an Oracle database.
# You will need to put the oracle.jdbc.OracleDriver class into your 
# classpath.
# In the great majority of cases, you want to use jhe desired version of a
# file odbc*.jar (previously JDBC distributed as classes12.zip),
# which you can get from the directory $ORACLE_HOME/jdbc/lib of any
# Oracle installation compatible with your server.
# Since you need to add to the classpath, you can't invoke SqlTool with
# the jar switch, like "java -jar .../sqltool.jar...".
# Put both the SqlTool jar and odbc*.jar in your classpath (and export!)
# and run something like "java org.hsqldb.util.SqlTool...".
# You could use the thick driver instead of the thin, but I know of no reason
# why any Java app should.

#urlid cardiff2
#url jdbc:oracle:thin:@aegir.admc.com:1521:TRAFFIC_SID
# Thin SID URLs must specify both port and SID, there are no defaults.
# Oracle listens to 1521 by default, so that's what you will usually specify.
# But can alternatively use global service name (not tnsnames.ora service
# alias, in which case the port does default to 1521):
#url jdbc:oracle:thin:@centos.admc.com/tstsid.admc
#username blaine
#password secretpassword
#driver oracle.jdbc.OracleDriver



# Template for a TLS-encrypted HSQLDB Server.
# Remember that the hostname in hsqls (and https) JDBC URLs must match the
# CN of the server certificate (the port and instance alias that follows 
# are not part of the certificate at all).
# You only need to set "truststore" if the server cert is not approved by
# your system default truststore (which a commercial certificate probably
# would be).

#urlid tls
#url jdbc:hsqldb:hsqls://db.admc.com:9001/lm2
#username BLAINE
#password asecret
#truststore ${user.home}/ca/db/db-trust.store


# Template for a Postgresql database
#urlid blainedb
#url jdbc:postgresql://idun.africawork.org/blainedb
#username blaine
#password losung1
#driver org.postgresql.Driver

# Template for a MySQL database.  MySQL has poor JDBC support.
#urlid mysql-testdb
#url jdbc:mysql://hostname:3306/dbname
#username root
#password hiddenpwd
#driver com.mysql.jdbc.Driver

# Note that "databases" in SQL Server and Sybase are traditionally used for
# the same purpose as "schemas" with more SQL-compliant databases.

# Template for a Microsoft SQL Server database using Microsoft's Driver
# (I find that the JTDS driver is much more responsive than Microsoft's).
# Port defaults to 1433.
# MSDN implies instances are port-specific, so can specify port or instname.
#urlid msprojsvr
# url/driver for Current 2011 JDBC Driver for Microsoft SQL Server:
# Requires just the new sqljdbc4.jar.  (Microsoft just loves back-slashes)
#url jdbc:sqlserver://hostname\instname;databaseName=dbname
# OR
#url jdbc:sqlserver://hostname;instanceName=instname;databaseName=dbname
#driver com.microsoft.jdbc.sqlserver.SQLServerDriver
# url/deriver for OLDER JDBC Driver:
#url jdbc:microsoft:sqlserver://hostname;DatabaseName=DbName;SelectMethod=Cursor
# The SelectMethod setting is required to do more than one thing on a JDBC
# session (I guess Microsoft thought nobody would really use Java for 
# anything other than a "hello world" program).
# This is for Microsoft's SQL Server 2000 driver (requires mssqlserver.jar
# and msutil.jar).
#driver com.microsoft.jdbc.sqlserver.SQLServerDriver
#username myuser
#password hiddenpwd

# Template for Microsoft SQL Server database using the JTDS Driver
# http://jtds.sourceforge.net  Jar file has name like "jtds-1.2.5.jar".
# Port defaults to 1433.
# MSDN implies instances are port-specific, so can specify port or instname.
#urlid nlyte
#username myuser
#password hiddenpwd
#url jdbc:jtds:sqlserver://myhost/nlyte;instance=MSSQLSERVER
# Where database is 'nlyte' and instance is 'MSSQLSERVER'.
# N.b. this is diff. from MS tools and JDBC driver where (depending on which
# document you read), instance or database X are specified like  HOSTNAME\X.
#driver net.sourceforge.jtds.jdbc.Driver

# Template for a Sybase database
#urlid sybase
#url jdbc:sybase:Tds:hostname:4100/dbname
#username blaine
#password hiddenpwd
# This is for the jConnect driver (requires jconn3.jar).
#driver com.sybase.jdbc3.jdbc.SybDriver

# Template for Embedded Derby / Java DB.
#urlid derby1
#url jdbc:derby:path/to/derby/directory;create=true
#username ${user.name}
#password any_noauthbydefault
#driver org.apache.derby.jdbc.EmbeddedDriver
# The embedded Derby driver requires derby.jar.
# There'a also the org.apache.derby.jdbc.ClientDriver driver with URL
# like jdbc:derby://&lt;server&gt;[:&lt;port&gt;]/databaseName, which requires
# derbyclient.jar.
# You can use \= to commit, since the Derby team decided (why???)
# not to implement the SQL standard statement "commit"!!
# Note that SqlTool can not shut down an embedded Derby database properly,
# since that requires an additional SQL connection just for that purpose.
# However, I've never lost data by not shutting it down properly.
# Other than not supporting this quirk of Derby, SqlTool is miles ahead of ij.
</pre>
<p>We will be using the "localhost-sa" sample urlid definition from
    the config file. The JDBC URL for this urlid is
    <code class="literal">jdbc:hsqldb:hsql://localhost</code>. That is the URL for the
    default catalog of a HyperSQL Listener running on the default port of the
    local host. You can read about URLs to connect to other catalogs with and
    without listeners in other chapters of this guide.</p>
<p>Run <code class="classname">SqlTool</code>. </p>
<div class="informalexample">
<pre class="screen"> java -jar path/to/sqltool.jar localhost-sa</pre>
</div>
<p> If you get a prompt, then all is well. If security is
    of any concern to you at all, then you should change the privileged
    password in the database. Use the command <code class="literal"><a class="literal" href="#set_password-sql">SET PASSWORD</a></code> command to change
    SA's password. </p>
<div class="informalexample">
<pre class="programlisting"> SET PASSWORD 'newpassword';</pre>
</div>
<p> Set a <span class="emphasis"><em>strong</em></span> password!</p>
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
<table border="0" summary="Note">
<tr>
<td valign="top" align="center" rowspan="2" width="25"><img alt="[Note]" src="../images/db/note.png"></td><th align="left">Note</th>
</tr>
<tr>
<td valign="top" align="left">
<p>If, like most UNIX System Administrators, you often need to
      make up strong passwords, I highly suggest the great little program
      <code class="filename"><a class="filename" href="https://sourceforge.net/projects/pwgen/" target="_top">pwgen</a></code>.
      You can probably get it where you get your other OS packages. The
      command <code class="literal">pwgen -1</code> is usually all you need.</p>
</td>
</tr>
</table>
</div>
<p>Note that with SQL-conformant databases like HyperSQL 2.0, user
    names and passwords are case sensitive. If you don't quote the name, it
    will be interpreted as upper-case, like any named SQL object. (Only for
    backwards compatibility, we do make an exception for the special user name
    SA, but you should always use upper-case "SA" nevertheless).</p>
<p>When you're finished playing, exit with the command
    <code class="literal">\q</code>.</p>
<p>If you changed the SA password, then you need to update the
    password in the <code class="filename">sqltool.rc</code> file
    accordingly.</p>
<p>You can, of course, also access the database with any JDBC client
    program. You will need to modify your classpath to include
    <code class="filename">hsqldb.jar</code> as well as your client class(es). You can
    also use the other HSQLDB client programs, such as
    <code class="classname">org.hsqldb.util.DatabasManagerSwing</code>, a graphical
    client with a similar purpose to <code class="classname">SqlTool</code>.</p>
<p>You can use any normal UNIX account to run the JDBC clients,
    including <code class="classname">SqlTool</code>, as long as the account has read
    access to the <code class="filename">sqltool.jar</code> file and to an
    <code class="filename">sqltool.rc</code> file. See the Utilities Guide about where
    to put <code class="filename">sqltool.rc</code>, how to execute sql files, and
    other <code class="classname">SqlTool</code> features.</p>
</div>
<div class="section" title="Create additional Accounts">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="uxc_addl_accts"></a>Create additional Accounts</h2>
</div>
</div>
</div>
<p>Connect to the database as SA (or any other Administrative user)
    and run <code class="literal"><a class="literal" href="#create_user-sql">CREATE USER</a></code> to
    create new accounts for your catalog. HSQLDB accounts are
    database-catalog-specific, not
    <code class="classname">Listener</code>-specific.</p>
<p>In SQL-compliant databases, all database objects are created in a
    <span class="emphasis"><em>schema</em></span>. If you don't specify a schema, then the new
    object will be created in the default schema. To create a database object,
    your account (the account that you connected with) must have the role
    <code class="literal">DBA</code>, or your account must have authorization for the
    target schema (see the CREATE SCHEMA command about this last). When you
    first create a HyperSQL catalog, it has only one database user-- SA, a DBA
    account, with an empty string password. You should set a password (as
    described above). You can create as many additional users as you wish. To
    make a user a DBA, you can use the "ADMIN" option to the <code class="literal"><a class="literal" href="#create_user-sql">CREATE USER</a></code> command, command, or
    GRANT the DBA Role to the account after creating it.</p>
<p>Once an object is created, the object creator and users with the
    DBA role will have all privileges to work with that object. Other users
    will have only the rights which the pseudo-user PUBLIC has. To give
    specific users more permissions, even rights to read objects, you can
    GRANT permissions for specific objects, grant Roles (which encompass a set
    of permissions), or grant the DBA Role itself.</p>
<p>Since only people with a database account may do anything at all
    with the database, it is often useful to permit other database users to
    view the data in your tables. To optimize performance, reduce contention,
    and minimize administration, it is often best to grant SELECT to PUBLIC on
    table-like objects that need to be accessed by multiple database users,
    with the significant exception of any data which you want to keep secret.
    (Similarly with EXECUTE priv for routines and USAGE priv for other object
    types). Note that this is not at all equivalent to giving the world or the
    Internet read access to your tables-- you are giving read access to people
    that have been given accounts for the target database catalog.</p>
</div>
<div class="section" title="Shutdown">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="uxc_shutdown"></a>Shutdown</h2>
</div>
</div>
</div>
<p>Do a clean database shutdown when you are finished with the database
    catalog. You need to connect up as SA or some other Admin user, of course.
    With SqlTool, you can run </p>
<div class="informalexample">
<pre class="screen"> java -jar path/to/sqltool.jar --sql 'shutdown;' localhost-sa</pre>
</div>
<p> You don't have to worry about stopping the
    <code class="classname">Listener</code> because it shuts down automatically when
    all served database catalogs are shut down.</p>
</div>
<div class="section" title="Running Hsqldb as a System Daemon">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="uxc_daemon"></a>Running Hsqldb as a System Daemon</h2>
</div>
</div>
</div>
<a name="N1624A" class="indexterm"></a>
<p>You can, of course, run HSQLDB through inittab on System V
    UNIXes, but usually an init script is more convenient and manageable. This
    section explains how to set up and use our UNIX init script. Our init
    script is only for use by root. (That is not to say that the
    <span class="emphasis"><em>Listener</em></span> will run as root-- it usually should
    not).</p>
<p>The main purpose of the init script is to start up a Listener for
    the database catalogs specified in your
    <code class="filename">server.properties</code> file; and to gracefully shut down
    these same catalogs. For each catalog defined by a
    <code class="varname">server.database.X</code> setting in your .properties file, you
    must define an administrative "urlid" in your
    <code class="filename">sqltool.rc</code> (these are used to access the catalogs for
    validation and shutdown purposes). Finally, you list the urlid names in
    your init script config file. If, due to firewall issues, you want to run
    a WebServer instead of a Server, then make sure you have a healthy
    WebServer with a webserver.properties set up, adjust your URLs in
    <code class="filename">sqltool.rc</code>, and set TARGET_CLASS in the config
    file.</p>
<p>By following the commented examples in the config file, you can
    start up any number of Server and/or WebServer listener instances with or
    without TLS encryption, and each listener instance can serve any number of
    HyperSQL catalogs (independent data sets), all with optimal efficiency
    from a single JVM process. There are instructions in the init script
    itself about how to run multiple, independently-configured JVM processes.
    Most UNIX installations, however, will run a single JVM with a single
    Listener instance which serves multiple catalogs, for easier management
    and more efficient resource usage.</p>
<p>After you have the init script set up, root can use it anytime to
    start or stop HSQLDB. (I.e., not just at system bootup or
    shutdown).</p>
<div class="section" title="Portability of hsqldb init script">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="uxc_init_script_portability"></a>Portability of <code class="filename">hsqldb</code> init script</h3>
</div>
</div>
</div>
<p>The primary design criterion of the init script is portability.
      It does not print pretty color startup/shutdown messages as is common in
      late-model Linuxes and HPUX; and it does not keep subsystem state files
      or use the startup/shutdown functions supplied by many UNIXes, because
      these features are all non-portable.</p>
<p>Offsetting these limitations, this one script does it's
      intended job great on the UNIX varieties I have tested, and can easily
      be modified to accommodate other UNIXes. While you don't have tight
      integration with OS-specific daemon administration guis, etc., you do
      have a well tested and well behaved script that gives good, utilitarian
      feedback.</p>
</div>
<div class="section" title="Init script Setup Procedure">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="uxc_init_script_setup"></a>Init script Setup Procedure</h3>
</div>
</div>
</div>
<p>The strategy taken here is to get the init script to run your
      single Server or WebServer first (as specified by TARGET_CLASS). After
      that's working, you can customize the JVM that is run by running
      additional Listener instances in it, running your own application in it
      (embedding), or even overriding HSQLDB behavior with your own overriding
      classes.</p>
<div class="procedure">
<ol class="procedure" type="1">
<li class="step" title="Step 1">
<p>Copy the init script <code class="filename"><a class="filename" href="#hsqldb.init-link"> sample/hsqldb.init</a></code> to
          <code class="filename">hsqldb</code> in the directory where init scripts live
          on your variety of UNIX. The most common locations are
          <code class="filename">/etc/init.d</code> or
          <code class="filename">/etc/rc.d/init.d</code> on System V style UNIXes,
          <code class="filename">/usr/local/etc/rc.d</code> on BSD style UNIXes, and
          <code class="filename">/Library/StartupItems/hsqldb</code> on OS X (you'll
          need to create the directory for the last).</p>
</li>
<li class="step" title="Step 2">
<p>View your <code class="filename">server.properties</code> file. Make a
          note of every catalog define by a
          <code class="varname">server.database.X</code> setting. A couple steps down,
          you will need to set up administrative access for each of these
          catalogs. If you are using our sample <code class="filename"><a class="filename" href="#server.properties-link"> server.properties</a></code>
          file, you will just need to set up access for the catalog specified
          with <code class="literal">file:db0/dbo</code>.</p>
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
<table border="0" summary="Note">
<tr>
<td valign="top" align="center" rowspan="2" width="25"><img alt="[Note]" src="../images/db/note.png"></td><th align="left">Note</th>
</tr>
<tr>
<td valign="top" align="left">
<p>Pre-2.0 versions of the hsqldb init script required use
            of .properties settings of the
            form<code class="varname">server.urlid.X</code>. These settings are obsolete
            and should be removed.</p>
</td>
</tr>
</table>
</div>
</li>
<li class="step" title="Step 3">
<p>Either copy <code class="varname">HSQLDB_OWNER</code>'s
          <code class="filename">sqltool.rc</code> file into root's home directory, or
          set the value of <code class="varname">AUTH_FILE</code> to the absolute path
          of <code class="varname">HSQLDB_OWNER</code>'s <code class="filename">sqltool.rc</code>
          file. This file is read directly by root, even if you run hsqldb as
          non-root (by setting <code class="varname">HSQLDB_OWNER</code> in the config
          file). If you copy the file, make sure to use
          <code class="literal">chmod</code> to restrict permissions on the new copy.
          The init script will abort with an appropriate exhortation if you
          have the permissions set incorrectly.</p>
<p>You need to set up a urlid stanza in your
          <code class="filename">sqltool.rc</code> file for network access (i.e. JDBC
          URL with hsql:, hsqls:, http:, or https:) for each catalog in your
          <code class="filename">server.properties</code> file. For our example, you
          need to define a stanza for the <code class="literal">file:db0/db0</code>
          catalog. You must supply for this catalog, a hsql: JDBC URL, an
          administrative user name, and the password.</p>
<div class="example">
<a name="N162C6"></a>
<p class="title">
<b>Example&nbsp;14.1.&nbsp;example sqltool.rc stanza</b>
</p>
<div class="example-contents">
<pre class="programlisting"> urlid localhostdb1
 url jdbc:hsqldb:hsql://localhost
 username SA
 password secret</pre>
</div>
</div>
<br class="example-break">
</li>
<li class="step" title="Step 4">
<p>Look at the comment towards the top of the init script
          which lists recommended locations for the configuration file for
          various UNIX platforms. Copy the sample config file <code class="filename"><a class="filename" href="#hsqldb.cfg-link">sample/hsqldb.cfg</a></code> to one of
          the listed locations (your choice). Edit the config file according
          to the instructions in it. For our example, you will set the value
          of <code class="varname">URLIDS</code> to <code class="literal">localhostdb1</code>,
          since that is the urlid name that we used in the
          <code class="filename">sqltool.rc</code> file.</p>
<pre class="programlisting"># $Id: hsqldb.cfg 3583 2010-05-16 01:49:52Z unsaved $

# Sample configuration file for HyperSQL Server Listener.
# See the "HyperSQL on UNIX" chapter of the HyperSQL User Guide.

# N.b.!!!!  You must place this in the right location for your type of UNIX.
# See the init script "hsqldb" to see where this must be placed and
# what it should be renamed to.

# This file is "sourced" by a Bourne shell, so use Bourne shell syntax.

# This file WILL NOT WORK until you set (at least) the non-commented
# variables to the appropriate values for your system.
# Life will be easier if you avoid all filepaths with spaces or any other
# funny characters.  Don't ask for support if you ignore this advice.

# The URLIDS setting below is new and REQUIRED.  This setting replaces the
# server.urlid.X settings which used to be needed in your Server's
# properties file.

# -- Blaine (blaine dot simpson at admc dot com)

JAVA_EXECUTABLE=/usr/bin/java

# Unless you copied the jar files from another system, this typically
# resides at $HSQLDB_HOME/lib/sqltool.jar, where $HSQLDB_HOME is your HSQLDB
# software base directory.
# The file name may actually have a version label in it, like
# sqltool-1.2.3.jar (in which case, you must specify the full name here).
# A 'hsqldb.jar' file (with or without version label) must reside in the same
# directory as the specified sqltool.jar file.
SQLTOOL_JAR_PATH=/opt/hsqldb-2.0.0/hsqldb/lib/sqltool.jar
# For the sample value above, there must also exist a file
# /opt/hsqldb-2.0.0/hsqldb/lib/hsqldb*.jar.

# Where the file "server.properties" or "webserver.properties" resides.
SERVER_HOME=/opt/hsqldb-2.0.0/hsqldb/data

# What UNIX user the server will run as.
# (The shutdown client is always run as root or the invoker of the init script).
# Runs as root by default, but you should take the time to set database file
# ownerships to another user and set that user name here.
HSQLDB_OWNER=hsqldb

# The HSQLDB jar file specified in HSQLDB_JAR_PATH above will automatically
# be in the class path.  This arg specifies additional classpath elements.
# To embed your own application, add your jar file(s) or class base
# directories here, and add your main class to the INVOC_ADDL_ARGS setting
# below.  Another common use-case for adding to your class path is to make
# classes available to the DB engines for SQL/JRT functions and procedures.
#SERVER_ADDL_CLASSPATH=/usr/local/dist/currencybank.jar

# For startup or shutdown failures, you can save a lot of debugging time by
# temporarily adjusting down MAX_START_SECS and MAX_TERMINATE_SECS to a
# little over what it should take for successful startup and shutdown on
# your system.

# We require all Server/WebServer instances to be accessible within 
# $MAX_START_SECS from when the Server/WebServer is started.
# Defaults to 60.
# Raise this is you are running lots of DB instances or have a slow server.
#MAX_START_SECS=200

# Max time to allow for JVM to die after all HSQLDB instances stopped.
# Defaults to 60.  Set high because the script will always continue as soon as
# the process has stopped.  The importance of this setting is, how long until
# a non-stopping-JVM-problem will be detected.
#MAX_TERMINATE_SECS=0

# NEW AND IMPORTANT!!!
# As noted at the top of this file, this setting replaces the old property
# settings server.urlid.X.
# Simply list the URLIDs for all DB instances which your *Server starts.
# Usually, these will exactly mirror the server.database.X settings in your
# server.properties or webserver.properties file.
# Each urlid listed here must be defined to a NETWORK url with Admin privileges
# in the AUTH_FILE specified below.  (Network type because we use this for
# inter-process communication)
# Separate multiple values with white space.  NO OTHER SPECIAL CHARACTERS!
# Make sure to quote the entire value if it contains white space separator(s).
URLIDS='localhostdb1'

# These are urlids # ** IN ADDITION TO URLIDS **, for instances which the init
# script should stop but not start.
# Most users will not need this setting.  If you need it, you'll know it.
# Defaults to none (i.e., only URLIDS will be stopped).
#SHUTDOWN_URLIDS='ondemand'

# SqlTool authentication file used only for shutdown.
# The default value will be sqltool.rc in root's home directory, since it is 
# root who runs the init script.
# (See the SqlTool chapter of the HyperSQL Utilities Guide if you don't
# understand this).
#AUTH_FILE=/home/blaine/sqltool.rc

# Typical users will leave this unset and it will default to
# org.hsqldb.server.Server.  If you need to run the HSQLDB WebServer class
# instead, due to a firewall or routing impediment, set this to
# org.hsqldb.server.WebServer, see the docs about running WebServr, and
# set up a "webserver.properties" file instead of a "server.properties".
# The JVM that is started can invoke many classes (see the following item
# about that), but this is the server that is used (1) to check status,
# (2) to shut down the JVM.
#TARGET_CLASS=org.hsqldb.server.WebServer

# This is where you may specify both command-line parameters to TARGET_CLASS,
# plus any number of additional progams to run (along with their command-line
# parameters).  The MainInvoker program is used to embed these multiple
# static main invocations into a single JVM, so see the API spec for
# org.hsqldb.util.MainInvoker if you want to learn more.
# N.b. You should only use this setting to set HSQLDB Server or WebServer
# parameters if you run multiple instances of this class, since you can use the
# server/webserver.properties file for a single instance.
# Every additional class (in addition to the TARGET_CLASS)
# must be preceded with an empty string, so that MainInvoker will know
# you are giving a class name.  MainInvoker will invoke the normal 
# static main(String[]) method of each such class.  
# By default, MainInvoker will just run TARGET_CLASS with no args.
# Example that runs just the TARGET_CLASS with the specified arguments:
#INVOC_ADDL_ARGS='-silent false'   #but use server.properties property instead!
# Example that runs the TARGET_CLASS plus a WebServer:
#INVOC_ADDL_ARGS='"" org.hsqldb.server.WebServer'
# Note the empty string preceding the class name.
# Example that starts TARGET_CLASS with an argument + a WebServer +
# your own application with its args (i.e., the HSQLDB Servers are
# "embedded" in your application).  (Set SERVER_ADDL_CLASSPATH too).:
#INVOC_ADDL_ARGS='-silent false "" org.hsqldb.server.WebServer "" com.acme.Stone --env prod localhost'
#   but use server.properties for -silent option instead!
# Example to run a non-TLS server in same JVM with a TLS server.  In this
# case, TARGET_CLASS is Server which will run both in TLS mode by virtue of 
# setting the tls, keyStore, and keyStorePassword settings in
# server*.properties, as described below; plus an "additional" Server with
# overridden 'tls' and 'port' settings:
#INVOC_ADDL_ARGS="'' org.hsqldb.server.Server --port 9002 --tls false"
# This is an important use case.  If you run more than one Server instance,
# you can specify different parameters for each here, even though only one
# server.properties file is supported.
# Note that you use nested quotes to group arguments and to specify the
# empty-string delimiter.

# The TLS_* settings have been obsoleted.
# To get your server running with TLS, set
# system.javax.net.ssl.keyStore=/path/to/your/private.keystore
# system.javax.net.ssl.keyStorePassword=secretPassword
# server.ssl=true
# IN server.properties or webserver.properties, and
# MAKE THE FILE OWNER-READ-ONLY!
# See the TLS Encryption section of the HyperSQL User Guide, paying attention
# to the security warning(s).
# If you are running with a private server cert, then you will also need to 
# set "truststore" in the your SqlTool config file (location is set by the
# AUTH_FILE variable in this file, or it must be at the default location for 
# HSQLDB_OWNER).

# Any JVM args for the invocation of the JDBC client used to verify DB
# instances and to shut them down (SqlToolSprayer).
# Server-side System Properties should normally be set with system.*
# settings in the server/webserver.properties file.
# This example specifies the location of a private trust store for TLS 
# encryption.
# For multiple args, put quotes around entire value.
# If you are starting just a TLS_encrypted Listener, you need to uncomment
# this so the init scripts uses TLS to connect.
# If using a private keystore, you also need to set "truststore" settings in
# the sqltool.rc file.
#CLIENT_JVMARGS=-Djavax.net.debug=ssl
# This sample value displays useful debugging information about TLS/SSL.

# Any JVM args for the server.
# For multiple args, put quotes around entire value.
#SERVER_JVMARGS=-Xmx512m
# You can set the "javax.net.debug" property on the server side here, in the
# same exact way as shown for the client side above.
</pre>
<p>
<span class="bold"><strong>Verify that the init script
          works.</strong></span>
</p>
<p>Just run </p>
<div class="informalexample">
<pre class="screen"> /path/to/hsqldb</pre>
</div>
<p> as root to see the arguments you may use.
          Notice that you can run</p>
<pre class="screen"> /path/to/hsqldb status</pre>
<p>at any time to see
          whether your HSQLDB <code class="classname">Listener</code> is
          running.</p>
<p>Re-run the script with each of the possible arguments to
          really test it good. If anything doesn't work right, then see the
          <a class="link" href="#uxc_inittrouble" title="Troubleshooting the Init Script">Troubleshooting the Init
      Script</a> section.</p>
</li>
<li class="step" title="Step 5">
<p>Tell your OS to run the init script upon system startup and
          shutdown. If you are using a UNIX variant that has
          <code class="filename">/etc/rc.conf</code> or
          <code class="filename">/etc/rc.conf.local</code> (like BSD variants and
          Gentoo), you must set "hsqldb_enable" to "YES" in either of those
          files. (Just run <code class="literal">cd /etc; ls rc.conf
          rc.conf.local</code> to see if you have one of these files). For
          good UNIXes that use System V style init, you must set up hard links
          or soft links either manually or with management tools (such as
          <code class="literal">chkconfig</code> or <code class="literal">insserv</code>) or Gui's
          (like run level editors).</p>
<p>This paragraph is for Mac OS X users only. If you followed the
          instructions above, your init script should reside at
          <code class="filename">/Library/StartupItems/hsqldb/hsqldb</code>. Now copy
          the file <code class="filename">StartupParameters.plist</code> from the
          directory <code class="filename">src/org.hsqldb/sample</code> of your HSQLDB
          distribution to the same directory as the init script. As long as
          these two files reside in
          <code class="filename">/Library/StartupItems/hsqldb</code>, your init script
          is active (for portability reasons, it doesn't check for a setting
          in <code class="filename">/etc/hostconfig</code>). You can run it as a
          <span class="emphasis"><em>Startup Item</em></span> by running </p>
<pre class="screen"> SystemStarter {start|stop|restart} Hsqldb</pre>
<p>
          Hsqldb is the service name. See the man page for
          <code class="classname">SystemStarter</code>. To disable the init script,
          wipe out the <code class="filename">/Library/StartupItems/hsqldb</code>
          directory. Hard to believe, but the Mac people tell me that during
          system shutdown the Startup Items don't run at all. Therefore, if
          you don't want your data corrupted, make sure to run "SystemStarter
          stop Hsqldb" before shutting down your Mac.</p>
</li>
</ol>
</div>
<p>Follow the examples in the config file to add additional
      classes to the server JVM's classpath and to execute additional classes
      in your JVM. (See the <code class="varname">SERVER_ADDL_CLASSPATH</code> and
      <code class="varname">INVOC_ADDL_ARGS</code> items).</p>
</div>
<div class="section" title="Troubleshooting the Init Script">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="uxc_inittrouble"></a>Troubleshooting the Init
      Script</h3>
</div>
</div>
</div>
<p>Definitely look at the init script log file, which is at an
      OS-sependent location, but is usually at
      <code class="filename">/var/log/hsqldb.log</code>.</p>
<p>Do a <code class="literal">ps</code> to look for processes containing the
      string <code class="literal">hsqldb</code>, and try to connect to the database
      from any client. If the init script starts up your database
      successfully, but incorrectly reports that it has not, then your problem
      is with specification of urlid(s) or SqlTool setup. If your database
      really did not start, then skip to the next paragraph. Verify that your
      config file assigns a urlid for each catalog defined in
      <code class="filename">server.properties</code> or
      <code class="filename">webserver.properties</code>, then verify that you can run
      <code class="classname">SqlTool</code> as root to connect to the catalogs with
      these urlids. (For the latter test, use the <code class="literal">--rcfile</code>
      switch if you are setting <code class="varname">AUTH_FILE</code> in the init
      script config file).</p>
<p>If your database really is not starting, then verify that you
      can <code class="literal">su</code> to the database owner account and start the
      database. The command <code class="literal">su USERNAME -c ...</code> won't work
      on most UNIXes unless the target user has a real login shell. Therefore,
      if you try to tighten up security by disabling this user's login shell,
      you will break the init script. If these possibilities don't pan out,
      then debug the init script or seek help, as described below.</p>
<p>To debug the init script, run it in verbose mode to see exactly
      what is happening (and perhaps manually run the steps that are suspect).
      To run an init script (in fact, any sh shell script) in verbose mode,
      use <code class="literal">sh</code> with the <code class="literal">-x</code> or
      <code class="literal">-v</code> switch, like </p>
<pre class="screen"> sh -x path/to/hsqldb start</pre>
<p>
      See the man page for <code class="literal">sh</code> if you don't know the
      difference between <code class="literal">-v</code> and
      <code class="literal">-x</code>.</p>
<p>If you want troubleshooting help, use the HSQLDB lists/forums.
      Make sure to include the revision number from your
      <code class="filename">hsqldb</code> init script (it's towards the top in the
      line that starts like "# $Id:"), and the output of a run of </p>
<pre class="screen"> sh -x path/to/hsqldb start &gt; /tmp/hstart.log 2&gt;&amp;1</pre>
</div>
</div>
<div class="section" title="Upgrading">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="uxc_upgrade"></a>Upgrading</h2>
</div>
</div>
</div>
<p>This section is for users who are using our UNIX init script, and
    who are upgrading their HyperSQL installation.</p>
<p>Most users will not have customized the init script itself, and
    your customizations will all be encapsulated in the init script
    configuration file. These users should just overwrite their init script
    with a new one from the HyperSQL installation, and manually merge config
    file settings. First, just copy the file
    <code class="filename">/sample/hsqldb.init</code> over top of of your init script
    (wherever it runs from). Then update your old config file according to the
    instructions in the new config file template at
    <code class="filename">sample/hsqldb.cfg</code>. You will have to change very few
    settings. If you are upgrading from a pre-2.0 installation to a post-2.0
    installation, you will need to (1) add the setting
    <code class="varname">URLIDS</code>, as described above and in the inline comments,
    and (2) replace variable <code class="varname">HSQLDB_JAR_PATH</code> with
    <code class="varname">SQLTOOL_JAR_PATH</code> which (if you haven't guessed) should
    be set to the path to your <code class="filename">sqltool.jar</code>
    file.</p>
<p>Users who customized their init script will need to merge their
    customizations into the new init script.</p>
</div>
</div>
<div class="chapter" title="Chapter&nbsp;15.&nbsp;Deployment Guide">
<div class="titlepage">
<div>
<div>
<h2 class="title">
<a name="deployment-chapt"></a>Chapter&nbsp;15.&nbsp;Deployment Guide</h2>
</div>
<div>
<div class="authorgroup">
<div class="author">
<h3 class="author">
<span class="firstname">Fred</span> <span class="surname">Toussi</span>
</h3>
<div class="affiliation">
<span class="orgname">The HSQL Development Group<br>
</span>
</div>
</div>
</div>
</div>
<div>
<p class="releaseinfo">$Revision: 5256 $</p>
</div>
<div>
<div class="legalnotice" title="Legal Notice">
<a name="N163B2"></a>
<p>Copyright 2002-2013 Fred Toussi. Permission is granted to
      distribute this document without any alteration under the terms of the
      HSQLDB license. Additional permission is granted to the HSQL Development
      Group to distribute this document with or without alterations under the
      terms of the HSQLDB license.</p>
</div>
</div>
<div>
<p class="pubdate">2014-02-13 18:21:41-0500</p>
</div>
</div>
</div>
<div class="toc">
<p>
<b>Table of Contents</b>
</p>
<dl>
<dt>
<span class="section"><a href="#dec_mem_disk_use">Memory and Disk Use</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#dec_table_mem_use">Table Memory Allocation</a></span>
</dt>
<dt>
<span class="section"><a href="#dec_result_mem_use">Result Set Memory Allocation</a></span>
</dt>
<dt>
<span class="section"><a href="#dec_temp_mem_use">Temporary Memory Use During Operations</a></span>
</dt>
<dt>
<span class="section"><a href="#dec_cache_mem_use">Data Cache Memory Allocation</a></span>
</dt>
<dt>
<span class="section"><a href="#dec_pool_mem_use">Object Pool Memory Allocation</a></span>
</dt>
<dt>
<span class="section"><a href="#dec_lob_mem_use">Lob Memory Usage</a></span>
</dt>
<dt>
<span class="section"><a href="#dec_disk_space">Disk Space</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#dec_managing_connections">Managing Database Connections</a></span>
</dt>
<dt>
<span class="section"><a href="#dec_app_dev_testing">Application Development and Testing</a></span>
</dt>
<dt>
<span class="section"><a href="#dec_tweaking">Tweaking the Mode of Operation</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#dec_embedded_desktop_db">Embedded Databases in Desktop Applications</a></span>
</dt>
<dt>
<span class="section"><a href="#dec_embedded_server_db">Embedded Databases in Server Applications</a></span>
</dt>
<dt>
<span class="section"><a href="#dec_mixed_mode_server">Mixed Mode : Embedding a HyperSQL Server (Listener)</a></span>
</dt>
<dt>
<span class="section"><a href="#dec_no_logging">Using HyperSQL Without Logging Data Change</a></span>
</dt>
<dt>
<span class="section"><a href="#dec_bulk_operations">Bulk Inserts, Updates and Deletes</a></span>
</dt>
<dt>
<span class="section"><a href="#dec_nio_access">Using NIO File Access</a></span>
</dt>
<dt>
<span class="section"><a href="#dec_server_db">Server Databases</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#dec_upgrade_database">Upgrading Databases</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#dec_upgrade_via_script">Upgrading From Older
      Versions</a></span>
</dt>
<dt>
<span class="section"><a href="#dec_script_manual_change">Manual Changes to the *.script File</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#dec_backware_compatibility">Backward Compatibility Issues</a></span>
</dt>
<dt>
<span class="section"><a href="#dec_dependency_applications">HyperSQL Dependency Settings for Applications</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#dec_hsqldb_version_pull">What version to Pull</a></span>
</dt>
<dt>
<span class="section"><a href="#dec_snapshot_repos">Using the HyperSQL Snapshot Repository</a></span>
</dt>
<dt>
<span class="section"><a href="#dec_maven_range_version">Range Versioning</a></span>
</dt>
</dl>
</dd>
</dl>
</div>
<div class="section" title="Memory and Disk Use">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="dec_mem_disk_use"></a>Memory and Disk Use</h2>
</div>
</div>
</div>
<a name="N163B9" class="indexterm"></a>
<p>Memory used by the program can be thought of as two distinct pools:
    memory used for table data which is not released unless the data is
    deleted and memory that can be released or is released automatically,
    including memory used for caching, building result sets and other internal
    operations such as storing the information needed for a rollback a
    transaction.</p>
<p>Most JVM implementations allocate up to a maximum amount of memory
    (usually 64 MB by default). This amount is generally not adequate when
    large memory tables are used, or when the average size of rows in cached
    tables is larger than a few hundred bytes. The maximum amount of allocated
    memory can be set on the Java command line that is used for running
    HyperSQL. For example, with Sun JVM, parameter -Xmx256m increases the
    amount to 256 MB.</p>
<div class="section" title="Table Memory Allocation">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dec_table_mem_use"></a>Table Memory Allocation</h3>
</div>
</div>
</div>
<p>The memory used for a MEMORY table is the sum of memory used by
      each row. Each MEMORY table row is a Java object that has 2 int or
      reference variables. It contains an array of objects for the fields in
      the row. Each field is an object such as <code class="classname">Integer</code>,
      <code class="classname">Long</code>, <code class="classname">String</code>, etc. In
      addition each index on the table adds a node object to the row. Each
      node object has 6 int or reference variables. As a result, a table with
      just one column of type INTEGER will have four objects per row, with a
      total of 10 variables of 4 bytes each - currently taking up 80 bytes per
      row. Beyond this, each extra column in the table adds at least a few
      bytes to the size of each row.</p>
</div>
<div class="section" title="Result Set Memory Allocation">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dec_result_mem_use"></a>Result Set Memory Allocation</h3>
</div>
</div>
</div>
<p>By default, all the rows in the result set are built in memory, so
      very large result sets may not be possible to build. A server mode
      databases releases the result set from the server memory once the
      database server has returned the result set. An
      <em class="glossterm">in-process</em> database releases the memory when the
      application program closes the <code class="classname">java.sql.ResultSet</code>
      object. A server mode database requires additional memory for returning
      result sets, as it converts the full result set into an array of bytes
      which is then transmitted to the client.</p>
<p>HyperSQL 2.0 supports disk-based result sets. The commands,
      <code class="literal">SET SESSION RESULT MEMORY ROWS &lt;integer&gt;</code> and
      <code class="literal">SET DATABASE DEFAULT RESULT MEMORY ROWS
      &lt;integer&gt;</code> specify a threshold for the number of rows.
      Results with row counts above the threshold are stored on disk. These
      settings also apply to temporary tables, views and subquery
      tables.</p>
<p>Disk-based result sets slow down the database operations and
      should be used only when absolutely necessary, perhaps with result sets
      that are larger than tens of thousands of rows.</p>
<p>In a server mode database, when the setFetchSize() method of the
      Statement interface is used to limit the number rows fetched, the whole
      result is held by the engine and is returned to the JDBC ResultSet in
      blocks of rows of the specified fetch size.</p>
</div>
<div class="section" title="Temporary Memory Use During Operations">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dec_temp_mem_use"></a>Temporary Memory Use During Operations</h3>
</div>
</div>
</div>
<p>When UPDATE and DELETE queries are performed on CACHED tables, the
      full set of rows that are affected, including those affected due to ON
      UPDATE actions, is held in memory for the duration of the operation.
      This means it may not be possible to perform deletes or updates
      involving very large numbers of rows of CACHED tables. Such operations
      should be performed in smaller sets. This memory is released as soon as
      the DELETE or UPDATE is performed.</p>
<p>When transactions support is enabled with SET AUTOCOMMIT FALSE,
      lists of all insert, delete or update operations are stored in memory so
      that they can be undone when ROLLBACK is issued. For CACHED tables, only
      the transaction information is held in memory, not the actual rows that
      have changed. Transactions that span thousands of modification to data
      will take up a lot of memory until the next COMMIT or ROLLBACK clears
      the list. Each row modification uses less than 100 bytes until
      COMMIT.</p>
<p>When subqueries or views are used in SELECT and other statements,
      transient tables are created and populated by the engine. If the
      <code class="literal">SET SESSION RESULT MEMORY ROWS &lt;integer&gt;</code>
      statement has been used, these transient tables are stored on disk when
      they are larger than the threshold.</p>
</div>
<div class="section" title="Data Cache Memory Allocation">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dec_cache_mem_use"></a>Data Cache Memory Allocation</h3>
</div>
</div>
</div>
<p>With CACHED tables, the data is stored on disk and only up to a
      maximum number of rows are held in memory at any time. The default is up
      to 50,000 rows. The SET FILES CACHE ROWS command or the
      <span class="property">hsqldb.cache_rows</span> connection property can be set to
      alter this amount. As any random subset of the rows in any of the CACHED
      tables can be held in the cache, the amount of memory needed by cached
      rows can reach the sum of the rows containing the largest field data.
      For example if a table with 100,000 rows contains 40,000 rows with 1,000
      bytes of data in each row and 60,000 rows with 100 bytes in each, the
      cache can grow to contain 50,000 of the smaller rows, but as explained
      further, only 10,000 or the large rows.</p>
<p>An additional property, <span class="property">hsqldb.cache_size</span> is
      used in conjunction with the <span class="property">hsqldb.cache_rows</span>
      property. This puts a limit in bytes on the total size of rows that are
      cached. The default values is 10,000KB. (This is the size of binary
      images of the rows and indexes. It translates to more actual memory,
      typically 2-4 times, used for the cache because the data is represented
      by Java objects.)</p>
<p>If memory is limited, the <span class="property">hsqldb.cache_rows</span>
      or <span class="property">hsqldb.cache_size</span> database properties can be
      reduced. In the example above, if the
      <span class="property">hsqldb.cache_size</span> is reduced from 10,000 to 5,000,
      it will allow the number of cached rows to reach 50,000 small rows, but
      only 5,000 of the larger rows.</p>
<p>Data for CLOB and BLOB columns is not cached and does not affect
      the CACHED table memory cache.</p>
<p>The use of Java NIO file access method also increases memory
      usage. Access with NIO improves database update speed and is used by
      default for data files up to 256 MB. For minimal memory use, nio access
      should be disabled.</p>
<p>The operating system usually allocates a large amount of buffer
      memory for speed up file read operations. Therefore when a lot of memory
      is available to the operating system, all database operations perform
      faster.</p>
</div>
<div class="section" title="Object Pool Memory Allocation">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dec_pool_mem_use"></a>Object Pool Memory Allocation</h3>
</div>
</div>
</div>
<p>HyperSQL uses a set of fast pools for immutable objects such as
      Integer, Long and short String objects that are stored in the database.
      In most circumstances, this reduces the memory footprint still further
      as fewer copies of the most frequently-used objects are kept in memory.
      The object pools are shared among all databases in the JVM. The size of
      each pool can be modified only by altering and recompiling the
      <code class="literal">org.hsqldb.store.ValuePool</code> class.</p>
</div>
<div class="section" title="Lob Memory Usage">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dec_lob_mem_use"></a>Lob Memory Usage</h3>
</div>
</div>
</div>
<p>Access to lobs is always performed in chunks, so it is perfectly
      possible to store and access a CLOB or BLOB that is larger than the JVM
      memory allocation. The actual total size of lobs is almost unlimited. We
      have tested with over 100 GB of lobs without any loss of
      performance.</p>
<p>By default, HyperSQL 2 uses memory-based tables for the lob schema
      (not the actual lob data). Therefore it is practical to store about
      100,000 individual lobs in the database with the default JVM memory
      allocation. More lobs can be stored with larger JVM memory allocations.
      In order to store more than a few hundreds of thousands of lobs, you can
      change the lob schema storage to CACHED tables with the following
      statements:</p>
<div class="example">
<a name="N16428"></a>
<p class="title">
<b>Example&nbsp;15.1.&nbsp;Using CACHED tables for the LOB schema</b>
</p>
<div class="example-contents">
<pre class="screen"> SET TABLE SYSTEM_LOBS.BLOCKS TYPE CACHED
 SET TABLE SYSTEM_LOBS.LOBS TYPE CACHED
 SET TABLE SYSTEM_LOBS.LOB_IDS TYPE CACHED
</pre>
</div>
</div>
<br class="example-break">
</div>
<div class="section" title="Disk Space">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dec_disk_space"></a>Disk Space</h3>
</div>
</div>
</div>
<p>With file: database, the engine uses the disk for storage of data
      and any change. For safely, the engine backs up the data internally
      during operation. Spare space, at least equal to the size of the .data
      and .script file is needed. The .lobs file is not backed up during
      operation as it is not necessary for safety.</p>
</div>
</div>
<div class="section" title="Managing Database Connections">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="dec_managing_connections"></a>Managing Database Connections</h2>
</div>
</div>
</div>
<p>In all running modes (server or <em class="glossterm">in-process</em>)
    multiple connections to the database engine are supported.
    <em class="glossterm">in-process</em> (standalone) mode supports connections
    from the client in the same Java Virtual Machine, while server modes
    support connections over the network from several different
    clients.</p>
<p>Connection pooling software can be used to connect to the database
    but it is not generally necessary. Connection pools may be used for the
    following reasons.</p>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>To allow new queries to be performed while a time-consuming
        query is being performed in the background. In HyperSQL, blocking
        depends on the transaction control model, the isolation level, and the
        current activity by other sessions.</p>
</li>
<li class="listitem">
<p>To limit the maximum number of simultaneous connections to the
        database for performance reasons. With HSQLDB this can be useful if
        your application is designed in a way that opens and closes
        connections for each small task. Also, the overall performance may be
        higher when fewer simultaneous connections are used. If you want to
        reduce the number of simultaneous sessions, you can use a connection
        pool with fewer pooled connections.</p>
</li>
</ul>
</div>
<p>An application that is not both multi-threaded and transactional,
    such as an application for recording user login and logout actions, does
    not need more than one connection. The connection can stay open
    indefinitely and reopened only when it is dropped due to network
    problems.</p>
<p>When using an <em class="glossterm">in-process</em> database, when the
    last connection to the database is closed, the database still remains
    open, waiting for the next connection to be made. From version 2.2.9, each
    time the last connection is closed all the data changes are logged and
    synched to disk.</p>
<p>An explicit SHUTDOWN command, with or without an argument, is
    required to close the database. A connection property, shutdown=true, can
    be used on the connection URL or in a properties object to shutdown the
    database when the last connection is closed.</p>
<p>When using a server database (and to some extent, an
    <em class="glossterm">in-process</em> database), care must be taken to avoid
    creating and dropping JDBC Connections too frequently. Failure to observe
    this will result in poor performance when the application is under heavy
    load.</p>
<p>A common error made by users in load-test simulations is to use a
    single client machine to open and close thousands of connections to a
    HyperSQL server instance. The connection attempts will fail after a few
    thousand because of OS restrictions on opening sockets and the delay that
    is built into the OS in closing them.</p>
</div>
<div class="section" title="Application Development and Testing">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="dec_app_dev_testing"></a>Application Development and Testing</h2>
</div>
</div>
</div>
<p>First thing to be aware of is the SQL conformance settings of
    HyperSQL. By default version 2 applies stricter conformance rules than
    version 1.8 and catches long strings or decimal values that do not fit
    within the specified length or precision settings. However, there are
    several conformance settings that are turned off by default. This is to
    enable easier migration from earlier versions, and also greater
    compatibility with databases such as MySQL that are sometimes very liberal
    with type conversions. The conformance settings are listed in the System
    Management chapter and their connection property equivalents are listed in
    the Database Properties chapter. Ideally, all the settings that are not
    for syntax compatibility with other databases should have a true value for
    best error checking. You can turn on the settings for syntax compatibility
    with another database if you are porting or testing applications targeted
    at the other database.</p>
<p>For application unit testing you can use an all-in-memory,
    in-process database.</p>
<p>If the tests are all run in one process, then the contents of a
    <em class="glossterm">mem:</em> database survives between tests. To release
    the contents you can use the SHUTDOWN command (an SQL command). You can
    even use multiple <em class="glossterm">mem:</em> databases in your tests and
    SHUTDOWN each one separately.</p>
<p>If the tests are in different processes and you want to keep the
    data between the tests, the best solution is to use a Server instance that
    has a <em class="glossterm">mem:</em> database. After the tests are done, you
    can SHUTDOWN this database, which will shutdown the server.</p>
<p>The Server has an option that allows databases to be created as
    needed by making a connection (see the Listeners Chapter). This option is
    useful for testing, as your server is never shut down when a database is
    shutdown. Each time you connect to the <em class="glossterm">mem:</em>
    database that is served by the Server, the database is created if it does
    not exist (i.e. has been previously shut down).</p>
<p>If you do not want to run a Server instance, and you need
    persistence between tests in different processes, then you should use a
    <em class="glossterm">file:</em> database. From version 2.2.9 when the last
    existing connection to the database is closed, the latest changes to the
    database are persisted fully with fsync. The database is still in an open
    state until it is shut down. You can use the
    <code class="literal">shutdown=true</code> connection property to close the database
    automatically after the connections are closed. The automatic sync and
    shutdown are mainly for test environment. In production environments you
    should execute the SHUTDOWN statement before your application is closed.
    This ensurs a quick start next time you connect to the database.</p>
<p>An alternative option is to use
    <code class="literal">hsqldb.write_delay=false</code> connection property, but this
    is slightly slower than the other option and should be used in situations
    where the test application does not close the connections. This option
    uses fsync after each commit. Even if the test process is aborted without
    shutting down the connections, all committed data is saved. It has been
    reported that some data access frameworks do not close all their
    connection to the database after the tests. In such situations, you need
    to use this option if you want the data to persist at the end of the
    tests</p>
<p>You may actually want to use a <em class="glossterm">file:</em>
    database, or a server instance that serves a <em class="glossterm">file:</em>
    database in preference to a <em class="glossterm">mem:</em> database. As
    HyperSQL logs the DDL and DML statements in the .log file, this file can
    be used to check what is being sent to the database. Note that UPDATE
    statements are represented by a DELETE followed by an INSERT statement.
    Statements are written out when the connection commits. The write delay
    also has an effect on how soon the statements are written out. By default,
    the write delay is 0.5 second.</p>
<p>The new SQL logging feature in version 2.2.x and later records all
    executed statements and can be used for debugging your application.</p>
<p>Some types of tests start with a database that already contains the
    tables and data, and perform various operations on it during the tests.
    You can create and populate the initial database then set the property
    "files_readonly=true" in the .properties file of the database. The tests
    can then modify the database, but these modifications are not persisted
    after the tests have completed.</p>
<p>Databases with "files_readonly=true" can be placed within the
    classpath and in a jar file. In this case, the connection URL must use the
    res: protocol, which treats the database as a resource.</p>
</div>
<div class="section" title="Tweaking the Mode of Operation">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="dec_tweaking"></a>Tweaking the Mode of Operation</h2>
</div>
</div>
</div>
<p>Different modes of operation and settings are used for different
    purposes. Some scenarios are discussed below:</p>
<div class="section" title="Embedded Databases in Desktop Applications">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dec_embedded_desktop_db"></a>Embedded Databases in Desktop Applications</h3>
</div>
</div>
</div>
<p>In this usage, the amount of data change is often limited and
      there is often a requirement to persist the data immediately. The
      default write delay of 0.5 second is fine for many applications. You can
      also use the property <code class="literal">hsqldb.write_delay_millis=100</code>
      to reduce it to 0.1 second, or the property
      <code class="literal">hsqldb.write_delay=false</code> to force a disk fsync after
      each commit. Before the application is closed, you should perform the
      SHUTDOWN command to ensure the database is opened instantly when it is
      next opened. Note you don't need to use SHUTDOWN COMPACT as
      routine.</p>
</div>
<div class="section" title="Embedded Databases in Server Applications">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dec_embedded_server_db"></a>Embedded Databases in Server Applications</h3>
</div>
</div>
</div>
<p>This usage involves a server application, such as a web
      application, connecting to an embedded HyperSQL instance. In this usage,
      the database is often accessed heavily, therefore performance and
      latency is a consideration. If the database is updated heavily, the
      default value of the WRITE DELAY property (0.5 sec) is often enough, as
      it is assumed the server or the application does not go down frequently.
      If it is necessary, you can reduce the WRITE DELAY to a small value (20
      ms) without impacting the update speed. If you reduce WRITE DELAY to
      zero, performance drops to the speed of disk file sync operation.</p>
<p>Alternatively, a server application can use an all-in-mem database
      instance for fast access, while sending the data changes to a
      persistent, disk based instance either periodically or in real
      time.</p>
</div>
<div class="section" title="Mixed Mode : Embedding a HyperSQL Server (Listener)">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dec_mixed_mode_server"></a>Mixed Mode : Embedding a HyperSQL Server (Listener)</h3>
</div>
</div>
</div>
<p>Since you won't be able to access
      <em class="glossterm">in-process</em> database instances from other
      processes, you will often want to run a Listener in your applications
      that use embedded databases. You can do this by starting up a Server or
      WebServer instance programmatically, but you could also use the class
      <code class="classname">org.hsqldb.util.MainInvoker</code> to start up your
      application and a HyperSQL Server or WebServer without any programming.
      MainInvoker is a general-purpose utility class to invoke the main
      methods of multiple classes. Each main class is followed by its
      arguments (if any), then an empty string to separate it from the next
      main class.</p>
<div class="example">
<a name="N164B6"></a>
<p class="title">
<b>Example&nbsp;15.2.&nbsp;MainInvoker Example</b>
</p>
<div class="example-contents">
<pre class="screen">  java -cp path/to/your/app.jar:path/to/hsqldb.jar org.hsqldb.util.MainInvoker com.your.main.App "" org.hsqldb.server.Server</pre>
</div>
</div>
<p>
<br class="example-break"> (Use ; instead of : to delimit classpath elements on
      Windows). The empty string separates your com.your.main.App invocation
      from the org.hsqldb.server.</p>
<p>Specify the same <em class="glossterm">in-process</em> JDBC URL to
      your app and in the <code class="filename">server.properties</code> file. You can
      then connect to the database from outside using a JDBC URL like
      <code class="literal">jdbc:hsqldb:hsql://hostname</code>, while connecting from
      inside the application using something like
      <code class="literal">jdbc:hsqldb:file:&lt;filepath of database&gt;</code>
      .</p>
<p>This tactic can be used to run off-the-shelf server
      applications with an embedded HyperSQL Server, without doing any
      coding.</p>
<p>
<code class="classname">MainInvoker</code> can be used to run any
      number of Java class main method invocations in a single JVM. See the
      API spec for <code class="classname"><a class="classname" href="#MainInvoker.html-link">
      MainInvoker</a></code> for details on its usage.</p>
</div>
<div class="section" title="Using HyperSQL Without Logging Data Change">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dec_no_logging"></a>Using HyperSQL Without Logging Data Change</h3>
</div>
</div>
</div>
<p>All file database that are not readonly, write changes to the .log
      file. There are scenarios where writing to the .log file can be turned
      off to improve performance, especially with larger databases. For these
      applications you can set the property
      <code class="literal">hsqldb.log_data=false</code> to disable the recovery log and
      speed up data change performance. The equivalent SQL command is SET
      FILES LOG FALSE.</p>
<p>With this setting, no data is logged, but all the changes to
      cached tables are written to the .data file. To persist all the data
      changes up to date, you can use the CHECKPOINT command. If you perform
      SHUTDOWN, the data is also persisted correctly. If you do not use
      CHECKPOINT or SHUTDOWN when you terminate the application, all the
      changes are lost and the database reverts to its original state when it
      is opened without losing any of the original data.</p>
<p>Your server applications can use a database as a temporary disk
      data cache which is not persisted past the lifetime of the application.
      For this usage, delete the database files when the application
      ends.</p>
<p>On some platforms, such as embedded devices which have a reliable
      storage device, this is also a useful option. Your application issues
      CHECKPOINT to save the changes made so far. This method of use reduces
      write operations on SSD devices. For this usage, the lock file should
      also be disabled with the connection property
      <code class="literal">hsqldb.lock_file=false</code>.</p>
</div>
<div class="section" title="Bulk Inserts, Updates and Deletes">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dec_bulk_operations"></a>Bulk Inserts, Updates and Deletes</h3>
</div>
</div>
</div>
<p>Bulk inserts, deletes and updates are performed with the best
      performance with the following method. The database remains safe and
      consistent using this method. In the event of a machine crash during the
      operation, the database can be recovered to the point just before the
      bulk operation.</p>
<div class="orderedlist">
<ol class="orderedlist" type="1">
<li class="listitem">
<p>Before the operation, execute the SET FILES LOG FALSE
          statement.</p>
</li>
<li class="listitem">
<p>Execute the CHECKPOINT statement.</p>
</li>
<li class="listitem">
<p>Perform all the bulk operations, using batched prepared
          statements. A batch size of 1000 to 10000 is adequate. Perform
          commit after each batch.</p>
</li>
<li class="listitem">
<p>After all the bulk operations are complete, execute the SET
          FILES LOG TRUE statement.</p>
</li>
<li class="listitem">
<p>Finally execute the CHECKPOINT statement.</p>
</li>
<li class="listitem">
<p>If you have performed many thousands of updates or deletes
          (not just inserts), it is a good idea to execute CHECKPOINT DEFRAG,
          instead of CHECKPOINT at the end.</p>
</li>
<li class="listitem">
<p>If things go wrong during the bulk operation, for example when
          a unique constraint violation aborts the operation, and you want to
          redo the whole operation, just use SHUTDOWN IMMEDIATELY instead of
          CHECKPOINT. When you restart the database it will revert to the
          state at the first CHECKPOINT and the bulk operation can be
          redone.</p>
</li>
</ol>
</div>
</div>
<div class="section" title="Using NIO File Access">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dec_nio_access"></a>Using NIO File Access</h3>
</div>
</div>
</div>
<p>This method of file access uses the operating system's
      memory-mapped file buffer for the <code class="literal">.data</code> file. For
      larger databases with CACHED tables, use of nio improves database access
      speed significantly. Performance improvements can be tenfold or even
      higher. By default, NIO is used for .data files from 16 MB up to 256 MB.
      You can increase the limit with the <code class="literal">SET FILES NIO SIZE
      &lt;value&gt;</code> statement. There should be enough RAM available
      to accommodate the memory mapped buffers. For vary large nio usage, a 64
      bit JVM must be used. The memory is not taken from the JVM memory
      allocation, therefore there is no need to increase the -Xmx parameter of
      the JVM. If not enough memory is available for the specified value, nio
      is not used.</p>
</div>
<div class="section" title="Server Databases">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dec_server_db"></a>Server Databases</h3>
</div>
</div>
</div>
<p>Running databases in a HyperSQL server is the best overall method
      of access. As the JVM process is separate from the application, this
      method is the most reliable as well as the most accessible method of
      running databases.</p>
</div>
</div>
<div class="section" title="Upgrading Databases">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="dec_upgrade_database"></a>Upgrading Databases</h2>
</div>
</div>
</div>
<a name="N16518" class="indexterm"></a>
<p>Any database that is not produced with the release version of
    HyperSQL 2.0 must be upgraded to this version.</p>
<div class="procedure" title="Procedure&nbsp;15.1.&nbsp;Upgrading Databases Created with Version 1.8.x">
<a name="N1651E"></a>
<p class="title">
<b>Procedure&nbsp;15.1.&nbsp;Upgrading Databases Created with Version 1.8.x</b>
</p>
<ol class="procedure" type="1">
<li class="step" title="Step 1">
<p>Open the database with the jar that created it and perform the
        SHUTDOWN statement as an SQL statement.</p>
</li>
<li class="step" title="Step 2">
<p>Open the database with the HyperSQL 2.0 jar.</p>
</li>
<li class="step" title="Step 3">
<p>Perform the SHUTDOWN COMPACT statement..</p>
</li>
</ol>
</div>
<p>The first step is to guarantee there is no .log file for the
    database. When upgrading an application that has been deployed on a large
    scale, it is sometimes not practical to perform the first step of this
    procedure (with the old jar). You can ignore the first step but you may
    lose part of the database statements that are stored in the .log file.
    Therefore you need to test with databases created with your application to
    make sure typical statements that are logged in the .log file are
    compatible with the new version. Examples of known incompatible statements
    are some DDL statements used for changing the data type or default values
    of column.</p>
<p>A note about SHUTDOWN modes. SHUTDOWN COMPACT is equivalent to
    SHUTDOWN SCRIPT plus opening the database and then performing a simple
    SHUTDOWN.</p>
<p>After upgrading a database, you may want to change some of its
    settings. For example, the new SET FILES BACKUP INCREMENT TRUE statement
    can improve the shutdown and checkpoint times of larger databases.</p>
<p>Once a database is upgraded to 2.0, it can no longer be used with
    previous versions of HyperSQL.</p>
<div class="section" title="Upgrading From Older Versions">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dec_upgrade_via_script"></a>Upgrading From Older
      Versions</h3>
</div>
</div>
</div>
<p>To upgrade from version 1.8.x with the default TEXT format script
      files, follow the instructions above. If the 1.8.x files have database
      script format set to BINARY or COMPRESSED (ZIPPED) you must issue the
      SET SCRIPTFORMAT TEXT and SHUTDOWN SCRIPT commands with the old version,
      then open with the new version of the engine. In most cases the upgrade
      is successful and complete.</p>
<p>It is strongly recommended to execute SHUTDOWN COMPACT after an
      automatic upgrade from previous versions.</p>
<p>If your database has been created with version 1.7.2 or 1.7.3,
      first upgrade to version 1.8.1 and perform a SHUTDOWN SCRIPT with this
      version. You can then upgrade the database to version 2.0.</p>
<p>To upgrade from older version database files (1.7.1 and older)
      that contain CACHED tables, use the SCRIPT procedure below. In all
      versions of HyperSQL, the <code class="literal">SCRIPT 'filename'</code> command
      (used as an SQL statement) allows you to save a full record of your
      database, including database object definitions and data, to a file of
      your choice. You can export a script file using the old version of the
      database engine and open the script as a database with 2.0.</p>
<div class="procedure" title="Procedure&nbsp;15.2.&nbsp;Upgrade Using the SCRIPT Procedure for Very Old Versions">
<a name="N16542"></a>
<p class="title">
<b>Procedure&nbsp;15.2.&nbsp;Upgrade Using the SCRIPT Procedure for Very Old
        Versions</b>
</p>
<ol class="procedure" type="1">
<li class="step" title="Step 1">
<p>Open the original database in the old version of
          DatabaseManager</p>
</li>
<li class="step" title="Step 2">
<p>Issue the SCRIPT command, for example <code class="literal">SCRIPT
          'newversion.script'</code> to create a script file containing a
          copy of the database.</p>
</li>
<li class="step" title="Step 3">
<p>SHUTDOWN this database.</p>
</li>
<li class="step" title="Step 4">
<p>Copy the original <code class="literal">*.properties</code> file into
          <code class="filename">newversion.properties</code> in the same directory as
          <code class="filename">newversion.script</code>
</p>
</li>
<li class="step" title="Step 5">
<p>Try to open the new database <code class="filename">newversion</code>
          using DatabaseManager of version 1.8.1.</p>
</li>
<li class="step" title="Step 6">
<p>If there is any inconsistency in the data, the script line
          number is reported on the console and the opening process is
          aborted. Edit and correct any problems in the
          <code class="filename">newversion.script</code> before attempting to open
          again. Use the guidelines in the next section (Manual Changes to the
          <code class="literal">.script</code> File). Use a programming editor that is
          capable of handling very large files and does not wrap long lines of
          text.</p>
</li>
</ol>
</div>
</div>
<div class="section" title="Manual Changes to the *.script File">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dec_script_manual_change"></a>Manual Changes to the *.script File</h3>
</div>
</div>
</div>
<p>In HyperSQL 2.0 the full range of ALTER TABLE commands is
      available to change the data structures and their names. However, if an
      old database cannot be opened due to data inconsistencies, or it uses
      index or column names that are not compatible with 2.0, manual editing
      of the <code class="literal">*.script</code> file can be performed and can be
      faster.</p>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>Version 2.0 does not accept duplicate names for indexes that
          were allowed before 1.7.2.</p>
</li>
<li class="listitem">
<p>Version 2.0 does not accept some table or column names that
          are SQL reserved keywords without double quoting.</p>
</li>
<li class="listitem">
<p>Version 2.0 does not accept unquoted table or column names
          which begin with an underscore, unless the connection
          <code class="literal">sql.regular_names</code> is set false.</p>
</li>
<li class="listitem">
<p>Version 2.0 is more strict with check conditions and default
          values.</p>
</li>
</ul>
</div>
<p>Other manual changes are also possible. Note that the
      <code class="literal">*.script</code> file must be the result of a SHUTDOWN SCRIPT
      and must contain the full data for the database. The following changes
      can be applied so long as they do not affect the integrity of existing
      data.</p>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>Names</p>
<p>Names of tables, columns and indexes can be changed. These
          changes must be consistent regarding foreign key constraint
          references.</p>
</li>
<li class="listitem">
<p>
<code class="literal">CHECK</code>
</p>
<p>A check constraint can always be removed.</p>
</li>
<li class="listitem">
<p>
<code class="literal">NOT NULL</code>
</p>
<p>A not-null constraint can always be removed.</p>
</li>
<li class="listitem">
<p>
<code class="literal">PRIMARY KEY</code>
</p>
<p>A primary key constraint can be removed. It cannot be removed
          if there is a foreign key referencing the column(s).</p>
</li>
<li class="listitem">
<p>
<code class="literal">UNIQUE</code>
</p>
<p>A UNIQUE constraint can be removed if there is no foreign key
          referencing the column(s).</p>
</li>
<li class="listitem">
<p>
<code class="literal">FOREIGN KEY</code>
</p>
<p>A FOREIGN KEY constraint can always be removed.</p>
</li>
<li class="listitem">
<p>
<code class="literal">COLUMN TYPES</code>
</p>
<p>Some changes to column types are possible. For example an
          INTEGER column can be changed to BIGINT.</p>
</li>
</ul>
</div>
<p>After completing the changes and saving the modified
      <code class="literal">.script</code> file, you can open the database as
      normal.</p>
</div>
</div>
<div class="section" title="Backward Compatibility Issues">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="dec_backware_compatibility"></a>Backward Compatibility Issues</h2>
</div>
</div>
</div>
<p>HyperSQL 2 conforms to the SQL Standard better than previous
    versions and has many more features. For these reasons, there may be some
    compatibility issues when converting old database, or using applications
    that were written for version 1.8.x or earlier. Some of the potential
    issues (and enhancements) are listed here. See the full list of connection
    properties for alternatives.</p>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>By default, when comparison strings, the shorter string is
        padded with spaces. This has an effect on comparing
        <code class="literal">'test'</code> and <code class="literal">'test '</code> which are now
        considered equal, despite the length difference. This behaviour is
        controlled by the default PAD SPACE property of collations, which can
        be changed to NO PAD. See the statement <code class="literal">SET DATABASE
        COLLATION &lt;name&gt; [ PAD SPACE | NO PAD ]</code>.</p>
</li>
<li class="listitem">
<p>User names and passwords are case-sensitive. Check the .script
        file of a database for the correct case of user name and password and
        use this form in the connection properties or on connection
        URL.</p>
</li>
<li class="listitem">
<p>It is now possible to specify the admin username and password
        for a new database (instead of SA and the empty password).</p>
</li>
<li class="listitem">
<p>HyperSQL 2.0 has several settings that relax its conformance to
        the SQL Standard in the areas of type conversion and object names.
        These settings can be turned on for maximum conformance.</p>
</li>
<li class="listitem">
<p>Check constraints must conform to the SQL Standard. A check
        constraint is rejected if it is not deterministic or retrospectively
        deterministic. When opening an old database, HyperSQL silently drops
        check constraints that no longer compile. See under check constraints
        for more detail about what is not allowed.</p>
</li>
<li class="listitem">
<p>Type declarations in column definition and in cast expressions
        must have the necessary size parameters.</p>
</li>
<li class="listitem">
<p>In connection with the above, an old database that did not have
        the <code class="literal">enforce_strict_size</code> property, is now converted
        to version 2.0 with the engine supplying the missing size parameters.
        For example, a VARCHAR column declaration that has no size, is given a
        32K size, a LONGVARCHAR column is given a 16MB size. Check these sizes
        are adequate for your use, and change the column definition as
        necessary.</p>
</li>
<li class="listitem">
<p>Column names in a GROUP BY clause were previously resolved to
        the column label. They are now resolved to column name first, and if
        the name does not match, to the column label.</p>
</li>
<li class="listitem">
<p>If two or more tables in a join contain columns with the same
        name, the columns cannot be referenced in join and where conditions.
        Use table names before column names to qualify the references to such
        columns. The <code class="literal">SET DATABASE SQL REFERENCES { TRUE | FALSE
        }</code> statement enables or disables this check.</p>
</li>
<li class="listitem">
<p>If the unqualified wild card is used, as in the statement SELECT
        * FROM ... no additional column references are allowed. A
        table-qualified wild card allows additional column references in the
        SELECT list</p>
</li>
<li class="listitem">
<p>Table definitions containing <code class="literal">GENERATED BY DEFAULT AS
        IDENTITY</code> but with no <code class="literal">PRIMARY KEY</code> do not
        automatically create a primary key. Database .script files made with
        1.8 are fine, as the <code class="literal">PRIMARY KEY</code> clause is always
        included. But the <code class="literal">CREATE TABLE</code> statements in your
        application program may assume an automatic primary key is created.
        The old shortcut, IDENTITY, is retained with the same meaning. So
        <code class="literal">CREATE TABLE T (ID IDENTITY, DAT VARCHAR(20))</code> is
        translated into <code class="literal">CREATE TABLE T(ID INTEGER GENERATED BY
        DEFAULT AS IDENTITY PRIMARY KEY, DAT VARCHAR(20))</code>. This last
        form is the correct way of defining both autoincrement and primary key
        in versions 1.8 and 2.0.</p>
</li>
<li class="listitem">
<p>CREATE ALIAS is now obsolete. Use the new function definition
        syntax. The <code class="classname">org.hsqldb.Library </code>class no longer
        exists. You should use the SQL form of the old library functions. For
        example, use <code class="literal">LOG(x)</code> rather than the direct form,
        <code class="literal">"org.hsqldb.Library.log"(x)</code>.</p>
</li>
<li class="listitem">
<p>The names of some commands for changing database and session
        properties have changed. See the list of statements in this
        chapter.</p>
</li>
<li class="listitem">
<p>Computed columns in SELECT statements which did not have an
        alias: These columns had no ResultMetaData label in version 1.8, but
        in version 2.0, the engine generates labels such as C1, C2.</p>
</li>
<li class="listitem">
<p>The issue with the JDBC ResultSetMetaData methods,
        <code class="literal">getColumnName(int column)</code> and
        <code class="literal">getColumnLabel(int column)</code> has been clarified by
        the JDBC 4 specification. <code class="literal">getColumName()</code> returns
        the underlying column name, while <code class="literal">getColumnLabel()</code>
        returns any specified or generated alias. HyperSQL 1.8 and 2.0 have a
        connection property, <code class="literal">get_column_name</code>, which
        defaults to true in version 2.0, but defaulted to false in some
        releases of version 1.8.x. You have to explicitly specify this
        property as false if you want (non-standard behaviour)
        <code class="literal">getColumnName()</code> to return the same value as
        <code class="literal">getColumnLabel()</code>.</p>
</li>
</ul>
</div>
</div>
<div class="section" title="HyperSQL Dependency Settings for Applications">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="dec_dependency_applications"></a>HyperSQL Dependency Settings for Applications</h2>
</div>
<div>
<h3 class="subtitle">Dependency settings using Gradle, Ivy, Maven, Groovy</h3>
</div>
</div>
</div>
<p>This section is about building applications that have build-time
    dependencies upon HyperSQL, and for executions that use a dependency
    library system. Examples of the second type are unit test runs, job runs
    triggered by a build system, or systems like Grape that pull libraries
    from the network at end-user run time.</p>
<div class="section" title="What version to Pull">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dec_hsqldb_version_pull"></a>What version to Pull</h3>
</div>
</div>
</div>
<p>The best option for most developers is to use our
      <span class="emphasis"><em>snapshot repository</em></span>, or at least to depend upon the
      latest public version of HyperSQL with a range pattern like
      <code class="literal">[2,)</code>. Here are exceptional cases where you should
      depend on a static version. </p>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">Your application has code dependencies upon
            version-specific details of the HyperSQL distribution. In this
            case, the specific dependency specification should be checked in
            to your source code control system alongside the code that
            manifests the version-dependency. If your code is enhanced to use
            a newer version of HyperSQL, you should update the version
            specification so that whenever code + configs are checked out, the
            dependency will always match the code.</li>
<li class="listitem">Your organization only allows the use of vetted
            libraries. In this case, you vigorously maintain your
            configurations, updating your dependencies and regression testing
            as soon as new versions of HyperSQL are vetted. To get the best
            performance and reliability from HyperSQL, you should urge the
            appropriate parties to vet new versions as soon as they are
            publicly released.</li>
<li class="listitem">You need precisely reproducible builds.</li>
</ul>
</div>
<p>If none of these situations apply to you, then follow
      the suggestions in the appropriate sections below. If you need to
      specify a specific version, follow the instructions in the
      range-versioning section but change the version range specifications to
      literal versions like <code class="literal">2.2.9</code>.</p>
</div>
<div class="section" title="Using the HyperSQL Snapshot Repository">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dec_snapshot_repos"></a>Using the HyperSQL Snapshot Repository</h3>
</div>
<div>
<h4 class="subtitle">Use the Latest &amp; Greatest with Snapshots</h4>
</div>
</div>
</div>
<p>For application testing, you may want to use the latest HSQLDB
      snapshot jar instead of the latest release jar. Snapshot jars contain
      fixes for reported bugs and the new features as they are being tested
      for the next release version. You can use the snapshot jars where you
      would normally include a dependency to a release jar as a Maven
      artifact. The HyperSQL Snapshot repository resides at <a class="link" href="http://hsqldb.org/repos/" target="_top">http://hsqldb.org/repos/</a>
</p>
<div class="note" title="Limitation of Classifiers" style="margin-left: 0.5in; margin-right: 0.5in;">
<table border="0" summary="Note: Limitation of Classifiers">
<tr>
<td valign="top" align="center" rowspan="2" width="25"><img alt="[Note]" src="../images/db/note.png"></td><th align="left"><a name="dec_classifier_limit"></a>Limitation of Classifiers</th>
</tr>
<tr>
<td valign="top" align="left">
<p>
<span class="emphasis"><em>Classifiers</em></span> are incompatible with real
        repository <span class="emphasis"><em>snapshots</em></span>. Builders can only publish
        one jar variant per product, and at this time our snapshot jars are
        always built debug-enabled with Java 6.</p>
</td>
</tr>
</table>
</div>
<p>Where you insert the &lt;repository&gt; element depends on
      whether you want the definition to be personal, shared, or
      project-specific, so see the Maven documentation about that. But you can
      paste this element verbatim:</p>
<div class="example">
<a name="N16664"></a>
<p class="title">
<b>Example&nbsp;15.3.&nbsp;HyperSQL Snapshot Repository Definition</b>
</p>
<div class="example-contents">
<pre class="programlisting"> &lt;repository&gt;
   &lt;releases&gt;
     &lt;enabled&gt;false&lt;/enabled&gt;
   &lt;/releases&gt;
   &lt;snapshots&gt;
     &lt;enabled&gt;true&lt;/enabled&gt;
     &lt;updatePolicy&gt;always&lt;/updatePolicy&gt;
     &lt;checksumPolicy&gt;fail&lt;/checksumPolicy&gt;
   &lt;/snapshots&gt;
   &lt;id&gt;hsqldb_snapshots&lt;/id&gt;
   &lt;name&gt;HyperSQL Snapshots&lt;/name&gt;
   &lt;url&gt;http://hsqldb.org/repos&lt;/url&gt;
   &lt;layout&gt;default&lt;/layout&gt;
 &lt;/repository&gt;</pre>
</div>
</div>
<br class="example-break">
<div class="section" title="Snapshot Dependency Specification Examples">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="dec_hsqldb_snap_dep_examples"></a>Snapshot Dependency Specification Examples</h4>
</div>
</div>
</div>
<div class="example">
<a name="N1666D"></a>
<p class="title">
<b>Example&nbsp;15.4.&nbsp;Sample Snapshot Ivy Dependency</b>
</p>
<div class="example-contents">
<pre class="programlisting">
 &lt;dependency org="org.hsqldb" name="hsqldb" rev="SNAPSHOT" conf="buildOnly"/&gt;</pre>
</div>
</div>
<br class="example-break">
<div class="example">
<a name="N16672"></a>
<p class="title">
<b>Example&nbsp;15.5.&nbsp;Sample Snapshot Maven Dependency</b>
</p>
<div class="example-contents">
<pre class="programlisting">
 &lt;dependency&gt;
   &lt;groupId&gt;org.hsqldb&lt;/groupId&gt;
   &lt;artifactId&gt;hsqldb&lt;/artifactId&gt;
   &lt;version&gt;SNAPSHOT&lt;/version&gt;
   &lt;!-- Scope defaults to "compile":
   &lt;scope&gt;test&lt;/scope&gt;
   --&gt;
 &lt;/dependency&gt;</pre>
</div>
</div>
<br class="example-break">
<div class="example">
<a name="N16677"></a>
<p class="title">
<b>Example&nbsp;15.6.&nbsp;Sample Snapshot Gradle Dependency</b>
</p>
<div class="example-contents">
<pre class="programlisting">
  dependencies.compile (group: 'org.hsqldb', name: 'hsqldb', version:'SNAPSHOT')
  dependencies {
      runtime 'org.hsqldb:hsqldb:SNAPSHOT',
              'org.hsqldb:sqltool:SNAPSHOT'
  }</pre>
</div>
</div>
<br class="example-break">
<p>If you want to use an <code class="filename">ivy.xml</code> file with a
        Gradle build, you will need use the <a class="link" href="https://github.com/unsaved/gradle-ivyxml-plugin" target="_top"> Ivyxml
        Gradle Plugin</a>. It just takes a few links of code in your
        <code class="filename">build.gradle</code> file to hook in
        <code class="literal">ivyxml</code>. See the <a class="link" href="https://github.com/unsaved/gradle-ivyxml-plugin/raw/master/README.txt" target="_top">
        Ivyxml documentation</a> to see exactly how. </p>
<div class="example">
<a name="N1668F"></a>
<p class="title">
<b>Example&nbsp;15.7.&nbsp;Sample Snapshot ivy.xml loaded by Ivyxml plugin</b>
</p>
<div class="example-contents">
<pre class="programlisting">
  &lt;ivy-module version="2.0"&gt;
  ...
  &lt;dependency org="org.hsqldb" name="hsqldb" rev="SNAPSHOT"/&gt;</pre>
</div>
</div>
<p>
<br class="example-break">
</p>
<div class="example">
<a name="N16694"></a>
<p class="title">
<b>Example&nbsp;15.8.&nbsp;Sample Snapshot Groovy Dependency, using Grape</b>
</p>
<div class="example-contents">
<pre class="programlisting">
@Grab(group='org.hsqldb', module='hsqldb', version='SNAPSHOT')</pre>
</div>
</div>
<br class="example-break">
</div>
</div>
<div class="section" title="Range Versioning">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="dec_maven_range_version"></a>Range Versioning</h3>
</div>
<div>
<h4 class="subtitle">Keeping up-to-date with Range Dependencies</h4>
</div>
</div>
</div>
<div class="note" title="Limitation of Maven Version Range Specifiers" style="margin-left: 0.5in; margin-right: 0.5in;">
<table border="0" summary="Note: Limitation of Maven Version Range Specifiers">
<tr>
<td valign="top" align="center" rowspan="2" width="25"><img alt="[Note]" src="../images/db/note.png"></td><th align="left"><a name="dec_maven_range"></a>Limitation of Maven Version Range Specifiers</th>
</tr>
<tr>
<td valign="top" align="left">
<p>Note that Ivy (and the many systems that use Ivy underneath,
        like Grape and Gradle) supports the opening exclusive
        <code class="literal">]</code> in addition to <code class="literal">[</code>, whereas
        Maven supports only the opening inclusive <code class="literal">[</code>
        specifier. See the relevant <a class="link" href="http://ant.apache.org/ivy/history/latest-milestone/ivyfile/dependency.html" target="_top">
        Ivy</a> or <a class="link" href="http://docs.codehaus.org/display/MAVEN/Dependency+Mediation+and+Conflict+Resolution#DependencyMediationandConflictResolution-DependencyVersionRanges" target="_top">
        Maven</a> documentation for details. There are special cases where
        you should depend on a specific version instead.</p>
</td>
</tr>
</table>
</div>
<div class="section" title="Range Dependency Specification Examples">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="dec_hsqldb_dyn_dep_examples"></a>Range Dependency Specification Examples</h4>
</div>
</div>
</div>
<div class="important" title="Important" style="margin-left: 0.5in; margin-right: 0.5in;">
<table border="0" summary="Important">
<tr>
<td valign="top" align="center" rowspan="2" width="25"><img alt="[Important]" src="../images/db/important.png"></td><th align="left">Important</th>
</tr>
<tr>
<td valign="top" align="left">
<p>For all examples below, when a range pattern is given, it
          means the latest version equal or greater than version
          <code class="literal">2</code>. If a classifier is shown, it is optional and
          you can skip it to get the default (no-classifier) jar.</p>
</td>
</tr>
</table>
</div>
<div class="example">
<a name="N166C0"></a>
<p class="title">
<b>Example&nbsp;15.9.&nbsp;Sample Range Ivy Dependency</b>
</p>
<div class="example-contents">
<pre class="programlisting">
 &lt;dependency org="org.hsqldb" name="hsqldb" rev="[2,)" conf="j6-&gt;default"/&gt;</pre>
<p>I give no example here of specifying a
          <span class="emphasis"><em>classifier</em></span> in <code class="filename">ivy.xml</code>
          because I have so far failed to get that to succeed. Classifiers in
          in <code class="filename">ivy.xml</code> are supported if using Gradle, as
          covered below.</p>
</div>
</div>
<br class="example-break">
<div class="example">
<a name="N166D0"></a>
<p class="title">
<b>Example&nbsp;15.10.&nbsp;Sample Range Maven Dependency</b>
</p>
<div class="example-contents">
<p>See <a class="link" href="#dec_maven_range" title="Limitation of Maven Version Range Specifiers">note above</a>
          about Maven range specifications.</p>
<pre class="programlisting">
 &lt;dependency&gt;
   &lt;groupId&gt;org.hsqldb&lt;/groupId&gt;
   &lt;artifactId&gt;hsqldb&lt;/artifactId&gt;
   &lt;version&gt;[2,)&lt;/version&gt;
   &lt;!-- Scope defaults to "compile":
   &lt;scope&gt;test&lt;/scope&gt;
     Use a classifier to pull one of our alternative jars:
   &lt;classifier&gt;jdk5&lt;/classifier&gt;
   --&gt;
 &lt;/dependency&gt;</pre>
</div>
</div>
<br class="example-break">
<div class="example">
<a name="N166DB"></a>
<p class="title">
<b>Example&nbsp;15.11.&nbsp;Sample Range Gradle Dependency</b>
</p>
<div class="example-contents">
<pre class="programlisting">
 dependencies.compile (group: 'org.hsqldb', name: 'hsqldb', version:'[2,)', classifier: 'jdk5')
 dependencies {
     runtime 'org.hsqldb:hsqldb:[2,):jdk6debug@jar',
             'org.hsqldb:sqltool:[2,):jdk6debug@jar'
 }</pre>
</div>
</div>
<br class="example-break">
<p>If you want to use an <code class="filename">ivy.xml</code> file with a
        Gradle build, you will need use the <a class="link" href="https://github.com/unsaved/gradle-ivyxml-plugin" target="_top"> Ivyxml
        Gradle Plugin</a>. It just takes a few links of code in your
        <code class="filename">build.gradle</code> file to hook in
        <code class="literal">ivyxml</code>. See the <a class="link" href="https://github.com/unsaved/gradle-ivyxml-plugin/raw/master/README.txt" target="_top">
        Ivyxml documentation</a> to see exactly how. </p>
<div class="example">
<a name="N166F3"></a>
<p class="title">
<b>Example&nbsp;15.12.&nbsp;Sample Range ivy.xml loaded by Ivyxml plugin</b>
</p>
<div class="example-contents">
<pre class="programlisting">
 &lt;ivy-module version="2.0" xmlns:m="http://ant.apache.org/ivy/maven"&gt;
 ...
 &lt;dependency org="org.hsqldb" name="hsqldb" rev="[2,)" m:classifier="jdk5"/&gt;</pre>
</div>
</div>
<p>
<br class="example-break">
</p>
<div class="example">
<a name="N166F8"></a>
<p class="title">
<b>Example&nbsp;15.13.&nbsp;Sample Range Groovy Dependency, using Grape</b>
</p>
<div class="example-contents">
<pre class="programlisting">
@Grab(group='org.hsqldb', module='hsqldb', version='[2,)', classifier='jdk6debug')</pre>
</div>
</div>
<br class="example-break">
</div>
</div>
</div>
</div>
<div class="appendix" title="Appendix&nbsp;A.&nbsp;Lists of Keywords">
<div class="titlepage">
<div>
<div>
<h1 class="title">
<a name="lists-app"></a>Lists of Keywords</h1>
</div>
<div>
<h3 class="subtitle">
<i>List of SQL Keywords</i>
</h3>
</div>
<div>
<div class="author">
<h3 class="author">
<span class="firstname">Fred</span> <span class="surname">Toussi</span>
</h3>
<div class="affiliation">
<span class="orgname">The HSQL Development Group<br>
</span>
</div>
</div>
</div>
<div>
<p class="releaseinfo">$Revision: 847 $</p>
</div>
<div>
<p class="pubdate">2014-02-13 18:21:41-0500</p>
</div>
</div>
</div>
<div class="toc">
<p>
<b>Table of Contents</b>
</p>
<dl>
<dt>
<span class="section"><a href="#lta_standard_keywords">List of SQL Standard Keywords</a></span>
</dt>
<dt>
<span class="section"><a href="#lta_disallowed_keywords">List of SQL Keywords Disallowed as HyperSQL Identifiers</a></span>
</dt>
<dt>
<span class="section"><a href="#lta_function_keywords">Special Function Keywords</a></span>
</dt>
</dl>
</div>
<div class="section" title="List of SQL Standard Keywords">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="lta_standard_keywords"></a>List of SQL Standard Keywords</h2>
</div>
</div>
</div>
<p>According to the SQL Standard, the SQL Language keywords cannot be
    used as identifiers (names of database objects such as columns and tables)
    without quoting.</p>
<p>HyperSQL has two modes of operation, which are selected with the
    <code class="literal">SET DATABASE SQL NAMES { TRUE | FALSE }</code> to allow or
    disallow the keywords as identifiers. The default mode is FALSE and allows
    the use of most keywords as identifiers. Even in this mode, keywords
    cannot be used as USER or ROLE identifiers. When the mode is TRUE, none of
    the keywords listed below can be used as identifiers.</p>
<p>All keywords can be used with double quotes as identifiers. For
    example</p>
<pre class="programlisting">  CREATE TABLE "ALL" ("AND" INT, "WHEN" INT)
  SELECT "AND" FROM "ALL" WHERE "WHEN" = 2020
</pre>
<p>ABS &bull; ALL &bull; ALLOCATE &bull; ALTER &bull; AND &bull; ANY &bull; ARE &bull; ARRAY &bull; AS &bull;
    ASENSITIVE &bull; ASYMMETRIC &bull; AT &bull; ATOMIC &bull; AUTHORIZATION &bull; AVG</p>
<p>BEGIN &bull; BETWEEN &bull; BIGINT &bull; BINARY &bull; BLOB &bull; BOOLEAN &bull; BOTH &bull;
    BY</p>
<p>CALL &bull; CALLED &bull; CARDINALITY &bull; CASCADED &bull; CASE &bull; CAST &bull; CEIL &bull;
    CEILING &bull; CHAR &bull; CHAR_LENGTH &bull; CHARACTER &bull; CHARACTER_LENGTH &bull; CHECK &bull; CLOB
    &bull; CLOSE &bull; COALESCE &bull; COLLATE &bull; COLLECT &bull; COLUMN &bull; COMMIT &bull; COMPARABLE &bull;
    CONDITION &bull; CONNECT &bull; CONSTRAINT &bull; CONVERT &bull; CORR &bull; CORRESPONDING &bull; COUNT
    &bull; COVAR_POP &bull; COVAR_SAMP &bull; CREATE &bull; CROSS &bull; CUBE &bull; CUME_DIST &bull; CURRENT &bull;
    CURRENT_CATALOG &bull; CURRENT_DATE &bull; CURRENT_DEFAULT_TRANSFORM_GROUP &bull;
    CURRENT_PATH &bull; CURRENT_ROLE &bull; CURRENT_SCHEMA &bull; CURRENT_TIME &bull;
    CURRENT_TIMESTAMP &bull; CURRENT_TRANSFORM_GROUP_FOR_TYPE &bull; CURRENT_USER &bull;
    CURSOR &bull; CYCLE</p>
<p>DATE &bull; DAY &bull; DEALLOCATE &bull; DEC &bull; DECIMAL &bull; DECLARE &bull; DEFAULT &bull;
    DELETE &bull; DENSE_RANK &bull; DEREF &bull; DESCRIBE &bull; DETERMINISTIC &bull; DISCONNECT &bull;
    DISTINCT &bull; DO &bull; DOUBLE &bull; DROP &bull; DYNAMIC</p>
<p>EACH &bull; ELEMENT &bull; ELSE &bull; ELSEIF &bull; END &bull; END_EXEC &bull; ESCAPE &bull; EVERY
    &bull; EXCEPT &bull; EXEC &bull; EXECUTE &bull; EXISTS &bull; EXIT &bull; EXP &bull; EXTERNAL &bull;
    EXTRACT</p>
<p>FALSE &bull; FETCH &bull; FILTER &bull; FIRST_VALUE &bull; FLOAT &bull; FLOOR &bull; FOR &bull;
    FOREIGN &bull; FREE &bull; FROM &bull; FULL &bull; FUNCTION &bull; FUSION</p>
<p>GET &bull; GLOBAL &bull; GRANT &bull; GROUP &bull; GROUPING</p>
<p>HANDLER &bull; HAVING &bull; HOLD &bull; HOUR</p>
<p>IDENTITY &bull; IN &bull; INDICATOR &bull; INNER &bull; INOUT &bull; INSENSITIVE &bull; INSERT
    &bull; INT &bull; INTEGER &bull; INTERSECT &bull; INTERSECTION &bull; INTERVAL &bull; INTO &bull; IS &bull;
    ITERATE</p>
<p>JOIN</p>
<p>LAG</p>
<p>LANGUAGE &bull; LARGE &bull; LAST_VALUE &bull; LATERAL &bull; LEAD &bull; LEADING &bull; LEAVE
    &bull; LEFT &bull; LIKE &bull; LIKE_REGEX &bull; LN &bull; LOCAL &bull; LOCALTIME &bull; LOCALTIMESTAMP &bull;
    LOOP &bull; LOWER</p>
<p>MATCH &bull; MAX &bull; MAX_CARDINALITY &bull; MEMBER &bull; MERGE &bull; METHOD &bull; MIN &bull;
    MINUTE &bull; MOD &bull; MODIFIES &bull; MODULE &bull; MONTH &bull; MULTISET</p>
<p>NATIONAL &bull; NATURAL &bull; NCHAR &bull; NCLOB &bull; NEW &bull; NO &bull; NONE &bull; NORMALIZE
    &bull; NOT &bull; NTH_VALUE &bull; NTILE &bull; NULL &bull; NULLIF &bull; NUMERIC</p>
<p>OCCURRENCES_REGEX &bull; OCTET_LENGTH &bull; OF &bull; OFFSET &bull; OLD &bull; ON &bull; ONLY
    &bull; OPEN &bull; OR &bull; ORDER &bull; OUT &bull; OUTER &bull; OVER &bull; OVERLAPS &bull; OVERLAY</p>
<p>PARAMETER &bull; PARTITION &bull; PERCENT_RANK &bull; PERCENTILE_CONT &bull;
    PERCENTILE_DISC &bull; POSITION &bull; POSITION_REGEX &bull; POWER &bull; PRECISION &bull; PREPARE
    &bull; PRIMARY &bull; PROCEDURE</p>
<p>RANGE &bull; RANK &bull; READS &bull; REAL &bull; RECURSIVE &bull; REF &bull; REFERENCES &bull;
    REFERENCING &bull; REGR_AVGX &bull; REGR_AVGY &bull; REGR_COUNT &bull; REGR_INTERCEPT &bull;
    REGR_R2 &bull; REGR_SLOPE &bull; REGR_SXX &bull; REGR_SXY &bull; REGR_SYY &bull; RELEASE &bull; REPEAT &bull;
    RESIGNAL &bull; RESULT &bull; RETURN &bull; RETURNS &bull; REVOKE &bull; RIGHT &bull; ROLLBACK &bull; ROLLUP
    &bull; ROW &bull; ROW_NUMBER &bull; ROWS</p>
<p>SAVEPOINT &bull; SCOPE &bull; SCROLL &bull; SEARCH &bull; SECOND &bull; SELECT &bull; SENSITIVE
    &bull; SESSION_USER &bull; SET &bull; SIGNAL &bull; SIMILAR &bull; SMALLINT &bull; SOME &bull; SPECIFIC &bull;
    SPECIFICTYPE &bull; SQL &bull; SQLEXCEPTION &bull; SQLSTATE &bull; SQLWARNING &bull; SQRT &bull; STACKED
    &bull; START &bull; STATIC &bull; STDDEV_POP &bull; STDDEV_SAMP &bull; SUBMULTISET &bull; SUBSTRING &bull;
    SUBSTRING_REGEX &bull; SUM &bull; SYMMETRIC &bull; SYSTEM &bull; SYSTEM_USER</p>
<p>TABLE &bull; TABLESAMPLE &bull; THEN &bull; TIME &bull; TIMESTAMP &bull; TIMEZONE_HOUR &bull;
    TIMEZONE_MINUTE &bull; TO &bull; TRAILING &bull; TRANSLATE &bull; TRANSLATE_REGEX &bull;
    TRANSLATION &bull; TREAT &bull; TRIGGER &bull; TRIM &bull; TRIM_ARRAY &bull; TRUE &bull;
    TRUNCATE</p>
<p>UESCAPE &bull; UNDO &bull; UNION &bull; UNIQUE &bull; UNKNOWN &bull; UNNEST &bull; UNTIL &bull;
    UPDATE &bull; UPPER &bull; USER &bull; USING</p>
<p>VALUE &bull; VALUES &bull; VAR_POP &bull; VAR_SAMP &bull; VARBINARY &bull; VARCHAR &bull;
    VARYING</p>
<p>WHEN &bull; WHENEVER &bull; WHERE &bull; WIDTH_BUCKET &bull; WINDOW &bull; WITH &bull; WITHIN &bull;
    WITHOUT &bull; WHILE</p>
<p>YEAR</p>
</div>
<div class="section" title="List of SQL Keywords Disallowed as HyperSQL Identifiers">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="lta_disallowed_keywords"></a>List of SQL Keywords Disallowed as HyperSQL Identifiers</h2>
</div>
</div>
</div>
<p>When the default <code class="literal">SET DATABASE SQL NAMES FALSE</code>
    mode is used, only a subset of SQL Standard keywords cannot be used as
    HyperSQL identifiers. The keywords are as follows:</p>
<p>ALL &bull; AND &bull; ANY &bull; AS &bull; AT &bull; AVG</p>
<p>BETWEEN &bull; BOTH &bull; BY</p>
<p>CALL &bull; CASE &bull; CAST &bull; COALESCE &bull; CORRESPONDING &bull; CONVERT &bull; COUNT &bull;
    CREATE &bull; CROSS</p>
<p>DEFAULT &bull; DISTINCT &bull; DROP</p>
<p>ELSE &bull; EVERY &bull; EXISTS &bull; EXCEPT</p>
<p>FOR &bull; FROM &bull; FULL</p>
<p>GRANT &bull; GROUP</p>
<p>HAVING</p>
<p>IN &bull; INNER &bull; INTERSECT &bull; INTO &bull; IS</p>
<p>JOIN</p>
<p>LEFT &bull; LEADING &bull; LIKE</p>
<p>MAX &bull; MIN</p>
<p>NATURAL &bull; NOT &bull; NULLIF</p>
<p>ON &bull; ORDER &bull; OR &bull; OUTER</p>
<p>PRIMARY</p>
<p>REFERENCES &bull; RIGHT</p>
<p>SELECT &bull; SET &bull; SOME &bull; STDDEV_POP &bull; STDDEV_SAMP &bull; SUM</p>
<p>TABLE &bull; THEN &bull; TO &bull; TRAILING &bull; TRIGGER</p>
<p>UNION &bull; UNIQUE &bull; USING</p>
<p>VALUES &bull; VAR_POP &bull; VAR_SAMP</p>
<p>WHEN &bull; WHERE &bull; WITH</p>
</div>
<div class="section" title="Special Function Keywords">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="lta_function_keywords"></a>Special Function Keywords</h2>
</div>
</div>
</div>
<p>HyperSQL supports SQL Standard functions that are called without
    parentheses. These functions include CURRENT_DATE, LOCALTIMESTAMP,
    TIMEZONE_HOUR, USER, etc. When the default <code class="literal">SET DATABASE SQL NAMES
    FALSE</code> mode is used, keywords that are names of SQL functions can
    be used as column names without double quotes in CREATE TABLE statements .
    But when the identifier is a column name and is referenced in SELECT or
    other statements, the keywords must be double quoted. Otherwise the result
    of the SQL function is returned instead of the column value.</p>
<p>HyperSQL also supports non-standard functions SYSTIMESTAMP, CURDATE,
    CURTIME, TODAY, SYSDATE and NOW which can be called with or without
    parentheses ( e.g. NOW() or NOW ). These names can be used as column
    names, but the names must be double quoted in SELECT and other
    statements.</p>
</div>
</div>
<div class="appendix" title="Appendix&nbsp;B.&nbsp;Building HyperSQL Jars">
<div class="titlepage">
<div>
<div>
<h1 class="title">
<a name="building-app"></a>Building HyperSQL Jars</h1>
</div>
<div>
<h3 class="subtitle">
<i>How to build customized or specialized jar files</i>
</h3>
</div>
<div>
<div class="author">
<h3 class="author">
<span class="firstname">Fred</span> <span class="surname">Toussi</span>
</h3>
<div class="affiliation">
<span class="orgname">The HSQL Development Group<br>
</span>
</div>
</div>
</div>
<div>
<p class="releaseinfo">$Revision: 5212 $</p>
</div>
<div>
<p class="pubdate">2014-02-13 18:21:41-0500</p>
</div>
</div>
</div>
<div class="toc">
<p>
<b>Table of Contents</b>
</p>
<dl>
<dt>
<span class="section"><a href="#bga_overview">Purpose</a></span>
</dt>
<dt>
<span class="section"><a href="#bga_gradle_invoke">Building with Gradle</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#bga_gradle_gui">Invoking a Gradle Build Graphically</a></span>
</dt>
<dt>
<span class="section"><a href="#bga_gradle_cmd">Invoking a Gradle Build from the Command Line</a></span>
</dt>
<dt>
<span class="section"><a href="#bga_gradle_using">Using Gradle</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#bga_building_ant">Building with Ant</a></span>
</dt>
<dd>
<dl>
<dt>
<span class="section"><a href="#bga_ant_obtaining">Obtaining Ant</a></span>
</dt>
<dt>
<span class="section"><a href="#bga_ant_build">Building Hsqldb with Ant</a></span>
</dt>
<dt>
<span class="section"><a href="#bga_old_jdk">Building for Older JDKs</a></span>
</dt>
</dl>
</dd>
<dt>
<span class="section"><a href="#bga_build_ide">Building with IDE Compilers</a></span>
</dt>
<dt>
<span class="section"><a href="#bga_codeswitcher">Hsqldb CodeSwitcher</a></span>
</dt>
<dt>
<span class="section"><a href="#bga_build_docs">Building Documentation</a></span>
</dt>
</dl>
</div>
<div class="section" title="Purpose">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="bga_overview"></a>Purpose</h2>
</div>
</div>
</div>
<p>From version 2.0, the supplied <code class="filename">hsqldb.jar</code>
    file is built with Java 1.6. If you want to run with a 1.5 or older JVM,
    or if you want to use an alternative jar
    (<code class="filename">hsqldb-min.jar</code>, etc.) you must build the desired jar
    with a Java SDK.</p>
<p>The Gradle task / Ant target <code class="literal">explainjars</code>
    reports the versions of Java and Ant actually used.</p>
</div>
<div class="section" title="Building with Gradle">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="bga_gradle_invoke"></a>Building with Gradle</h2>
</div>
</div>
</div>
<p>As noted above, Java SDK 5 or later is required.</p>
<p>Unlike most software build systems, you do not need to have the
    Gradle system installed on your computer to use it. You don't need to
    understand the details to use it, but this is the purpose of the
    <code class="filename">gradlew</code> <span class="emphasis"><em>wrapper</em></span> scripts that you
    can see in HyperSQL's <code class="filename">build</code> directory. If you want or
    need to learn more about Gradle, you can start on the <a class="link" href="http://gradle.org/documentation" target="_top"> Gradle Documentation
    page</a> on the <a class="link" href="http://gradle.org" target="_top"> Gradle web
    site</a>.</p>
<div class="note" title="Gradle honors JAVA_HOME" style="margin-left: 0.5in; margin-right: 0.5in;">
<table border="0" summary="Note: Gradle honors JAVA_HOME">
<tr>
<td valign="top" align="center" rowspan="2" width="25"><img alt="[Note]" src="../images/db/note.png"></td><th align="left">Gradle honors <code class="varname">JAVA_HOME</code></th>
</tr>
<tr>
<td valign="top" align="left">
<p>Gradle can find the Java to use by finding out where
      <code class="literal">java</code> is available from, but if environmental variable
      <code class="varname">JAVA_HOME</code> is set, that will override. Therefore, if
      you have multiple JREs or JDKs installed, or don't know if multiple are
      installed, you should set environmental variable
      <code class="varname">JAVA_HOME</code> to definitively eliminate all
      ambiguity.</p>
</td>
</tr>
</table>
</div>
<div class="important" title="Rare Gotcha" style="margin-left: 0.5in; margin-right: 0.5in;">
<table border="0" summary="Important: Rare Gotcha">
<tr>
<td valign="top" align="center" rowspan="2" width="25"><img alt="[Important]" src="../images/db/important.png"></td><th align="left">Rare Gotcha</th>
</tr>
<tr>
<td valign="top" align="left">
<p>Depending on your operating system, version, and how you
      installed your JDK, Gradle may not be able to find the JDK. Gradle will
      inform you if this happens. The easiest way to fix this problem is to
      set environmental variable <code class="varname">JAVA_HOME</code> to the root
      directory where your Java SDK is installed. (See previous
      <span class="emphasis"><em>note</em></span> for justification). So as not to get bogged
      down in the details here, if you don't know how to set an environmental
      variable, I ask you to utilize a search engine.</p>
</td>
</tr>
</table>
</div>
<a name="N16812" class="indexterm"></a>
<div class="section" title="Invoking a Gradle Build Graphically">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="bga_gradle_gui"></a>Invoking a Gradle Build Graphically</h3>
</div>
</div>
</div>
<p>Whether from an IDE, a shortcut or launch icon, to run a Gradle
      graphical build you just need to execute either the file
      <code class="literal">gradle-gui.cmd</code> (on Windows) or
      <code class="literal">gradle-gui</code> (all other platforms), both of which
      reside in the <code class="filename">build</code> directory of your HyperSQL
      distribution.</p>
<p>I will explain how to invoke a graphical Gradle build from
      Windows Explorer and from Eclipse IDE. Users of other operating systems
      should be able to infer how to use their own file manager in the same
      way as shown for Internet Explorer. Users who want a desktop shortcut,
      quick-launch icon should first get Gradle working from a file manager
      (like Windows Explorer), then seek out instructions for making
      shortcuts, etc. for your operating system or desktop manager. (Try a web
      search).</p>
<p>Some IDEs, like IntelliJ have direct support for Gradle. The
      Spring Framework team is working on a sophisticated plugin for using
      Gradle with their IDE. But I'm going to document a very basic setup done
      with Eclipse because it's serviceable and a very similar procedure is
      likely to work with all other IDEs.</p>
<p>If you do use and enjoy Gradle, then I urge you to make the
      product better by registering a free account for yourself at <a class="link" href="http://issues.gradle.org/" target="_top">the Gradle Jira site</a> and
      vote for critical usability issues like <a class="link" href="http://issues.gradle.org/browse/GRADLE-427" target="_top">GRADLE-427</a>,
      <a class="link" href="http://issues.gradle.org/browse/GRADLE-1855" target="_top">GRADLE-1855</a>,
      <a class="link" href="http://issues.gradle.org/browse/GRADLE-1870" target="_top">GRADLE-1870</a>,
      <a class="link" href="http://issues.gradle.org/browse/GRADLE-1871" target="_top">GRADLE-1871</a>,
      to help to improve the product.</p>
<div class="procedure" title="Procedure&nbsp;B.1.&nbsp;Invoking Gradle GUI from Windows Explorer">
<a name="N1683F"></a>
<p class="title">
<b>Procedure&nbsp;B.1.&nbsp;Invoking Gradle GUI from Windows Explorer</b>
</p>
<ol class="procedure" type="1">
<li class="step" title="Step 1">
<p>Start up Windows explorer. Depending on your Windows
          version, it will be in the Start Menu, or in the menu you get when
          you right-click <span class="guimenuitem">Start</span>.</p>
</li>
<li class="step" title="Step 2">
<p>Navigate Windows Explorer to the <code class="filename">build</code>
          directory within your HyperSQL installation.</p>
</li>
<li class="step" title="Step 3">
<p>Find an icon or line (depending on your Windows Explorer
          view) for the file <code class="filename">gradle-gui.cmd</code>. If there is
          no listing for <code class="filename">gradle-gui.cmd</code>, but two listings
          for <code class="filename">gradle-gui</code>, then you want the one signified
          by text, icon, or mouse-over tooltip, as a <span class="emphasis"><em>batch or CMD
          file</em></span>. Double-click this item.</p>
</li>
</ol>
</div>
<div class="procedure" title="Procedure&nbsp;B.2.&nbsp;Setting up Gradle Graphical Builds from Eclipse IDE">
<a name="N1685D"></a>
<p class="title">
<b>Procedure&nbsp;B.2.&nbsp;Setting up Gradle Graphical Builds from Eclipse IDE</b>
</p>
<ol class="procedure" type="1">
<li class="step" title="Step 1">
<p>From Eclipse, use pulldown menu
          <span class="guimenuitem">Run</span> / <span class="guimenuitem">External
          Tools</span> / <span class="guimenuitem">External Tools
          Configurations...</span>.</p>
</li>
<li class="step" title="Step 2">
<p>Right-click on Program in the left navigator Right-click
          <span class="guilabel">Project</span> in the left navigator panel and select
          <span class="guimenuitem">New</span>. (Depending on the state of your
          workspace, instead of <span class="guimenuitem">New</span> in the
          context-sensitive menu, there may be a
          <span class="guilabel">New_configuration</span> or similar item nested under
          <span class="guilabel">Program</span>, in which case you should select
          that).</p>
</li>
<li class="step" title="Step 3">
<p>To the right, change the value in the
          <span class="guilabel">Name:</span> field to <code class="literal">HSQLDB Gradle</code>
          (or whatever name you want for this launcher config (this Gradle
          launcher is only for your HSQLDB project).</p>
</li>
<li class="step" title="Step 4">
<p>Make sure that the <span class="guilabel">Main</span> tab is
          selected.</p>
</li>
<li class="step" title="Step 5">
<p>For the <span class="guimenuitem">Location:</span> field, use the
          <span class="guimenuitem">Browse Workspace...</span> button to navigate to
          and select the <code class="filename">gradle-gui.cmd</code> (Windows) or
          <code class="filename">gradle-gui</code> (other) file in the
          <code class="filename">build</code> directory of your HyperSQL project.
          </p>
<div class="mediaobject" align="center">
<img src="eclipse-gradle-cfg.png" align="middle"><div class="caption">
<p>Configuring Gradle GUI Launcher in Eclipse</p>
</div>
</div>
<p> Depending on your Eclipse version and workspace
          setup, the value populated into the <span class="guilabel">Location:</span>
          field after you select the program may appear very differently than
          in this screen shot.</p>
</li>
<li class="step" title="Step 6">
<p>Click the <span class="guilabel">Run</span> button. The Gradle Gui
          should run. (If you just <span class="guilabel">Apply</span> and
          <span class="guilabel">Close</span> here instead of <span class="guilabel">Run</span>,
          the new Gradle launch item will not be added to the pulldown and
          toolbar menus).</p>
</li>
</ol>
</div>
<p>After doing the Eclipse setup, you can use pulldown menu
      <span class="guimenuitem">Run</span> / <span class="guimenuitem">External
      Tools</span> or the equivalent tool bar button button to launch
      the Gradle Gui. </p>
<div class="mediaobject" align="center">
<img src="eclipse-gradle-invoke.png" align="middle"><div class="caption">
<p>Invoking Gradle GUI from Eclipse</p>
</div>
</div>
<p> You can do this and close it after each use, or, to
      avoid startup lag, minimize it when it's not in use.</p>
</div>
<div class="section" title="Invoking a Gradle Build from the Command Line">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="bga_gradle_cmd"></a>Invoking a Gradle Build from the Command Line</h3>
</div>
</div>
</div>
<p>You can invoke graphical and non-graphical Gradle builds from
      the command-line.</p>
<div class="procedure">
<ol class="procedure" type="1">
<li class="step" title="Step 1">
<p>Get a command-line shell. Windows users can use either
          <span class="guimenuitem">Start/Run...</span> or <span class="guimenuitem">Start/Start
          Search</span>, and enter "<code class="literal">cmd</code>".
          Non-windows users will know how to get a shell.</p>
</li>
<li class="step" title="Step 2">
<p>In the shell, cd to the <code class="filename">build</code>
          directory under the root directory where you extracted or installed
          HyperSQL to. (Operating system search or find functions can be used
          if you can't find it quickly by poking around on the command line or
          with Windows Explorer, etc.).</p>
</li>
<li class="step" title="Step 3">
<p>Windows users can ignore this step. UNIX shell users should
          ensure that the current directory (<code class="literal">.</code>) is in their
          search path, or prefix their <code class="literal">gradlew</code> or
          <code class="literal">gradle-gui</code> command in the next step with
          <code class="literal">./</code> (e.g., like
          <code class="literal">./gradlew</code>).</p>
</li>
<li class="step" title="Step 4">
<p>In the shell, run either <code class="literal">gradle-gui</code> for
          a graphical build; or <code class="literal">gradlew</code> for a text-based
          build.</p>
</li>
</ol>
</div>
<p>The <code class="filename">gradle-gui</code> file is our own wrapper
      script for <code class="literal">gradlew --gui</code>. Be aware that both
      <code class="filename">gradle-gui</code> and <code class="literal">gradlew --gui</code>
      suffer from the limitation that the <code class="literal">--gui</code> switch is
      mutually exclusive with most or all other arguments (including tasks). I
      have registered GRADLE bugs 1861 and 1863 about this.</p>
</div>
<div class="section" title="Using Gradle">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="bga_gradle_using"></a>Using Gradle</h3>
</div>
</div>
</div>
<div class="section" title="Using Text-based Gradle">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="bga_gradle_text"></a>Using Text-based Gradle</h4>
</div>
</div>
</div>
<p>If you ran just <code class="literal">gradlew</code> or
        <code class="literal">gradlew.bat</code>, then you will be presented with simple
        instructions for how to do everything that you want to do. Basically,
        you will run the same <code class="literal">gradlew</code> or
        <code class="literal">gradle.bat</code> command repeatedly, with different
        switches and arguments.</p>
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
<table border="0" summary="Note">
<tr>
<td valign="top" align="center" rowspan="2" width="25"><img alt="[Note]" src="../images/db/note.png"></td><th align="left">Note</th>
</tr>
<tr>
<td valign="top" align="left">
<p>Gradle's -v switch reports version details more directly
          than the <code class="literal">explainjars</code> task does, from the
          operating system version to the Groovy version (the language
          interpreter used for Gradle instructions).</p>
</td>
</tr>
</table>
</div>
</div>
<div class="section" title="Using the Gradle GUI">
<div class="titlepage">
<div>
<div>
<h4 class="title">
<a name="bga_gradle_using_gui"></a>Using the Gradle GUI</h4>
</div>
</div>
</div>
<div class="mediaobject" align="center">
<img src="gradle-gui.png" align="middle"><div class="caption">
<p>Sample Gradle GUI Screen</p>
</div>
</div>
<div class="procedure" title="Procedure&nbsp;B.3.&nbsp;First Time using Gradle Gui">
<a name="N1693E"></a>
<p class="title">
<b>Procedure&nbsp;B.3.&nbsp;First Time using Gradle Gui</b>
</p>
<ol class="procedure" type="1">
<li class="step" title="Step 1">
<p>It takes the Gradle gui a while to start up, because,
            similar to an IDE, it is generating a list of details about
            available tasks.</p>
</li>
<li class="step" title="Step 2">
<p>In the main window, in the top panel, with the
            <span class="guilabel">Task Tree</span> tab selected, you have the list of
            public tasks, sorted alphabetically. Down bottom is displayed the
            output of the last task(s) execution. (After startup it will show
            the output of the task <code class="literal">tasks</code>).</p>
</li>
<li class="step" title="Step 3">
<p>Scroll to the <code class="literal">help</code> task and click it
            once to select it, then click the green
            <span class="guilabel">Execute</span> toolbar button above. (You could also
            have double-clicked the item, but you can use the selection
            procedure to pick multiple tasks with Control or Shift keys to
            execute multiple tasks in a single run-- and the tasks will
            execute in the same order that you had selected them).</p>
</li>
<li class="step" title="Step 4">
<p>Scroll through and read the output of the
            <code class="literal">help</code> task in the bottom panel. Where this help
            screen speaks about verbosity switches, you can accomplish the
            same thing by using the <span class="guimenuitem">Setup</span> tab.
            Whenever Gradle output (in the bottom panel) talks about running
            <code class="literal">gradlew &lt;sometask&gt;...</code>, you can execute
            the specified task(s) by selecting and executing them like we just
            did.</p>
</li>
</ol>
</div>
<div class="note" title="Gradle GUI Limitations" style="margin-left: 0.5in; margin-right: 0.5in;">
<table border="0" summary="Note: Gradle GUI Limitations">
<tr>
<td valign="top" align="center" rowspan="2" width="25"><img alt="[Note]" src="../images/db/note.png"></td><th align="left">Gradle GUI Limitations</th>
</tr>
<tr>
<td valign="top" align="left">
<p>The Gradle GUI is fairly new and lacks some of the power
          available to text-based users. Most significantly, in my opinion, is
          the following item for which I have opened Gradle
          <span class="emphasis"><em>issues</em></span> 1855. There is no convenient way to set
          build properties. If you want to change Ant or Gradle build
          settings, edit the text file <code class="filename">build.properties</code>
          in the HyperSQL <code class="filename">build</code> directory (creating it if
          it doesn't exist yet), and enter your properties using Java
          properties file syntax. (You can also use
          <code class="filename">local-docbook.properties</code> in the same way for
          DocBook-specific properties).</p>
</td>
</tr>
</table>
</div>
</div>
</div>
</div>
<div class="section" title="Building with Apache Ant">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="bga_building_ant"></a>Building with Apache Ant</h2>
</div>
</div>
</div>
<a name="N16979" class="indexterm"></a>
<p>You should use version 1.7.x of Ant (Another Neat Tool) to do Ant
    builds with HyperSQL.</p>
<div class="section" title="Obtaining Ant">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="bga_ant_obtaining"></a>Obtaining Ant</h3>
</div>
</div>
</div>
<p>Ant is a part of the Jakarta/Apache Project.</p>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">
<a class="link" href="http://ant.apache.org" target="_top">Home of the Apache
          Ant project</a>
</li>
<li class="listitem">The <a class="link" href="http://ant.apache.org/manual/install.html#installing" target="_top">
          Installing Ant</a> page of the <a class="link" href="http://ant.apache.org/manual" target="_top">Ant Manual</a>. Follow
          the directions for your platform.</li>
</ul>
</div>
</div>
<div class="section" title="Building Hsqldb with Ant">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="bga_ant_build"></a>Building Hsqldb with Ant</h3>
</div>
</div>
</div>
<p>Once you have unpacked the zip package for hsqldb, under the
      <code class="filename">/hsqldb</code> folder, in <code class="filename">/build</code>
      there is a <code class="filename">build.xml</code> file that builds the
      <code class="filename">hsqldb.jar</code> with Ant (Ant must be already
      installed). To use it, change to <code class="filename">/build</code> then
      type:</p>
<div class="informalexample">
<pre class="screen"> ant -projecthelp</pre>
</div>
<p>This displays the available ant targets, which you can supply
      as command line arguments to ant. These include</p>
<div class="variablelist">
<table border="0">
<col valign="top" align="left">
<tbody>
<tr>
<td>
<p>
<span class="term">hsqldb</span>
</p>
</td><td>to build the <code class="filename">hsqldb.jar</code>
            file</td>
</tr>
<tr>
<td>
<p>
<span class="term">explainjars</span>
</p>
</td><td>Lists all targets which build jar files, with an
            explanation of the purposes of the different jars.</td>
</tr>
<tr>
<td>
<p>
<span class="term">clean</span>
</p>
</td><td>to clean up the /classes directory that is
            created</td>
</tr>
<tr>
<td>
<p>
<span class="term">clean-all</span>
</p>
</td><td>to remove the old jar and doc files as well</td>
</tr>
<tr>
<td>
<p>
<span class="term">javadoc</span>
</p>
</td><td>to build javadoc</td>
</tr>
<tr>
<td>
<p>
<span class="term">hsqldbmain</span>
</p>
</td><td>to build a smaller jar for HSQLDB that does not contain
            utilities</td>
</tr>
<tr>
<td>
<p>
<span class="term">hsqljdbc</span>
</p>
</td><td>to build an extremely small jar containing only the
            client-side JDBC driver (can connect only to a HyperSQL
            Server).</td>
</tr>
<tr>
<td>
<p>
<span class="term">hsqldbmin</span>
</p>
</td><td>to build a small jar that supports
            <span class="emphasis"><em>in-process</em></span> catalogs, but neither running nor
            connecting to HyperSQL Servers.</td>
</tr>
<tr>
<td>
<p>
<span class="term">sqltool</span>
</p>
</td><td>to build sqltool.jar, which contains only the SqlTool
            classes.</td>
</tr>
<tr>
<td>
<p>
<span class="term">...</span>
</p>
</td><td>Many more targets are available. Run <code class="literal">ant
            -p</code> and <code class="literal">ant explainjars</code>.</td>
</tr>
</tbody>
</table>
</div>
<p>HSQLDB can be built in any combination of two JRE (Java Runtime
      Environment) versions and many jar file sizes.</p>
<p>A jar built with an older JRE is compatible for use with a
      newer JRE (you can compile with Java 1.5 and run with 1.6). But the
      newer JDBC capabilities of the JRE will be not be available.</p>
<p>The client jar (<code class="filename">hsqljdbc.jar</code>) contains
      only the HSQLDB JDBC Driver client. The smallest engine jar
      (<code class="filename">hsqldbmin.jar</code>) contains the engine and the HSQLDB
      JDBC Driver client. The default size (<code class="filename">hsqldb.jar</code>)
      also contains server mode support and the utilities. The largest size
      (<code class="filename">hsqldbtest.jar</code>)includes some test classes as well.
      Before building the <code class="filename">hsqldbtest.jar</code> package, you
      should download the junit jar from <a class="link" href="http://www.junit.org" target="_top">http://www.junit.org</a> and put it in the
      <code class="filename">/lib</code> directory, alongside
      <code class="filename">servlet.jar</code>, which is included in the .zip
      package.</p>
<p>If you want your code built for high performance, as opposed to
      debugging (in the same way that we make our production distributions),
      make a file named <code class="filename">build.properties</code> in your build
      directory with the contents </p>
<div class="informalexample">
<pre class="screen">build.debug: false</pre>
</div>
<p>The resulting Java binaries will be faster and
      smaller, at the cost of exception stack traces not identifying source
      code locations (which can be extremely useful for debugging).</p>
<p>After installing Ant on your system use the following command
      from the <code class="filename">/build</code> directory. Just run <code class="literal">ant
      explainjars</code> for a concise list of all available jar
      files.</p>
<div class="informalexample">
<pre class="screen">ant explainjars</pre>
</div>
<p>The command displays a list of different options for building
      different sizes of the HSQLDB Jar. The default is built using:</p>
<div class="example">
<a name="N16A2D"></a>
<p class="title">
<b>Example&nbsp;B.1.&nbsp;Buiding the standard Hsqldb jar file with Ant</b>
</p>
<div class="example-contents">
<pre class="screen">ant hsqldb</pre>
</div>
</div>
<br class="example-break">
<p>The Ant method always builds a jar with the JDK that is used by
      Ant and specified in its JAVA_HOME environment variable.</p>
</div>
<div class="section" title="Building for Older JDKs">
<div class="titlepage">
<div>
<div>
<h3 class="title">
<a name="bga_old_jdk"></a>Building for Older JDKs</h3>
</div>
</div>
</div>
<p>HyperSQL version 2.0 cannot be directly compiled or used with JDK
      1.4. It may be possible to use the RetroTranslator tool to achieve this.
      The suggested procedure is as follows: First use Gradle or Ant with JDK
      1.5 and build the jar. Then translate the jar using RetroTranslator with
      backport (which bundles replacement classes for concurrency control).
      This translation should cover the concurrency features that are specific
      to version 1.5 and later.</p>
<div class="informalexample">
<pre class="screen">ant switchtojdk14
ant hsqldb
-- translate the jar
</pre>
</div>
</div>
</div>
<div class="section" title="Building with IDE Compilers">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="bga_build_ide"></a>Building with IDE Compilers</h2>
</div>
</div>
</div>
<p>All HyperSQL source files are supplied ready to compile. There is
    no complex pre-compile stage. It is therefore possible to compile the
    sources with an IDE, without using Gradle or Ant. Only if compilation with
    Java 1.5 is required, you should first run the Gradle task (or Ant target)
    before compiling and remove from the source directories a few source files
    that are specific to Java 6 (these are listed in the build.xml
    file).</p>
</div>
<div class="section" title="Hsqldb CodeSwitcher">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="bga_codeswitcher"></a>Hsqldb CodeSwitcher</h2>
</div>
</div>
</div>
<p>CodeSwitcher is a tool to manage different version of Java source
    code. It allows to compile HyperSQL for different JDKs. It is something
    like a precompiler in C but it works directly on the source code and does
    not create intermediate output or extra files.</p>
<p>CodeSwitcher is used internally in the Ant build. You do not have
    to invoke it separately to compile HyperSQL.</p>
<p>CodeSwitcher reads the source code of a file, removes comments
    where appropriate and comments out the blocks that are not used for a
    particular version of the file. This operation is done for all files of a
    defined directory, and all subdirectories.</p>
<div class="example">
<a name="N16A4D"></a>
<p class="title">
<b>Example&nbsp;B.2.&nbsp;Example source code before CodeSwitcher is run</b>
</p>
<div class="example-contents">
<pre class="programlisting">
 ...

 //#ifdef JAVA2

     properties.store(out,"hsqldb database");

 //#else

 /*

     properties.save(out,"hsqldb database");

 */

 //#endif

 ...</pre>
</div>
</div>
<br class="example-break">
<p>The next step is to run CodeSwitcher.</p>
<div class="example">
<a name="N16A54"></a>
<p class="title">
<b>Example&nbsp;B.3.&nbsp;CodeSwitcher command line invocation</b>
</p>
<div class="example-contents">
<pre class="screen">
 java org.hsqldb.util.CodeSwitcher . -JAVA2</pre>
</div>
</div>
<br class="example-break">
<p>The '.' means the program works on the current directory (all
    subdirectories are processed recursively). <code class="literal">-JAVA2</code> means
    the code labelled with JAVA2 must be switched off.</p>
<div class="example">
<a name="N16A5E"></a>
<p class="title">
<b>Example&nbsp;B.4.&nbsp;Source code after CodeSwitcher processing</b>
</p>
<div class="example-contents">
<pre class="programlisting">
     ...

 //#ifdef JAVA2

 /*

     pProperties.store(out,"hsqldb database");

 */

 //#else

     pProperties.save(out,"hsqldb database");

 //#endif

     ...</pre>
</div>
</div>
<br class="example-break">
<p>For detailed information on the command line options run
    <code class="classname">java org.hsqldb.util.CodeSwitcher</code>. Usage examples
    can be found in the build.xml file in the <code class="filename">/build</code>
    directory.</p>
</div>
<div class="section" title="Building Documentation">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="bga_build_docs"></a>Building Documentation</h2>
</div>
</div>
</div>
<p>The JavaDoc can be built simply by invoking the javadoc
    task/target with Gradle or Ant.</p>
<p>The two Guides (the one you are reading now plus the Utilities user
    guide) are in DocBook XML source format. To rebuild to PDF or one of the
    HTML output formats from the XML source, run the Gradle target
    <code class="literal">gen-docs</code> (or the Ant target
    <code class="literal">gen-docs</code>). Instructions will be displayed. In
    particular </p>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">Obtain the HyperSQL documentation source. We no longer
          include our Guide source files in our main distribution zip file, in
          order to keep it small. You may want to build from the trunk branch
          or the latest release tag. You can download a static snapshot
          tarball from
          http://hsqldb.svn.sourceforge.net/viewvc/hsqldb/base/trunk/ or under
          http://hsqldb.svn.sourceforge.net/viewvc/hsqldb/base/tags/ , or you
          can export a snapshot or check out a work area using a Subversion
          client.</li>
<li class="listitem">You must locally install the DocBook set of image files,
          which are available for download from Sourceforge. The
          <code class="literal">gen-docs</code> task/target will tell you of a Gradle
          task that you can use to download and install them automatically.
          This Gradle task, <code class="literal">installDbImages</code>, will tell you
          how to edit a properties text file to tell it what directory to
          install the files into. (Command-line, as opposed to GUI, builders,
          can use the Gradle <code class="literal">-P</code> switch to set the property,
          instead of editing, if they prefer).</li>
<li class="listitem">You can optionally install the entire DocBook style sheets
          (instead of just the DocBook images within it), character entity
          definitions, and RNG schema file, to speed up doc build times and
          minimize dependency of future builds upon network or Internet. An
          intermediate approach would be to install these resources onto an
          HTTP server or shared network drive of your own. See the comments at
          the top of the file <code class="filename">build.xml</code> in the HyperSQL
          <code class="filename">build</code> directory about where to obtain these
          things and how to hook them in. The same Gradle task
          <code class="literal">installDbImages</code> explained above can download and
          install the entire stylesheet bundle (this option is offered the
          first time that you run the <code class="literal">installDbImages</code>
          task).</li>
</ul>
</div>
<div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;">
<table border="0" summary="Tip">
<tr>
<td valign="top" align="center" rowspan="2" width="25"><img alt="[Tip]" src="../images/db/tip.png"></td><th align="left">Tip</th>
</tr>
<tr>
<td valign="top" align="left">
<p>If running Gradle, you probably want to turn logging up to
      level <span class="emphasis"><em>info</em></span> for generation and validation tasks,
      because the default <span class="emphasis"><em>warn/lifecycle</em></span> level doesn't
      give much feedback.</p>
</td>
</tr>
</table>
</div>
<p>The task/target <code class="literal">validate-docs</code> is also very
    useful to DocBook builders.</p>
<p>The documentation license does not allow you to post
    modifications to our guides, but you can modify them for internal use by
    your organization, and you can use our DocBook system to write new DocBook
    documents related or unrelated to HyperSQL. To create new DocBook
    documents, create a subdirectory off of <code class="filename">doc-src</code> for
    each new document, with the main DocBook source file within having same
    name as the directory plus <code class="literal">.xml</code>. See the peer directory
    <code class="filename">util-guide</code> or <code class="filename">guide</code> as an
    example. If you use the high-level tasks/target
    <code class="literal">gen-docs</code> or <code class="literal">validate-docs</code>, then copy
    and paste to add new stanzas to these targets in file
    <code class="filename">build.xml</code>.</p>
<p>Editors of DocBook documents (see previous paragraph for motive)
    may find it useful to have a standalone XML validator so you can do your
    primary editing without involvement of the build system. Use the Gradle
    target <code class="literal">standaloneValidation</code> for this. It will tell you
    how to set a build property to tell it where to install the validator, and
    will give instructions on how to use it.</p>
<p>There are several properties that can be used to dramatically
    decrease run times for partial doc builds. Read about these properties in
    comment at the top of the file <code class="filename">build-docbook.xml</code> in
    the <code class="filename">build</code> directory. </p>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">validation.skip</li>
<li class="listitem">html.skip</li>
<li class="listitem">chunk.skip</li>
<li class="listitem">fo.skip</li>
<li class="listitem">pdf.skip</li>
<li class="listitem">doc.name</li>
<li class="listitem">doc.target</li>
</ul>
</div>
<p>See the file <code class="filename">doc-src/readme-docauthors.txt</code>
    for details about our DocBook build system (though as I write this it is
    somewhat out of date).</p>
</div>
</div>
<div class="appendix" title="Appendix&nbsp;C.&nbsp;HyperSQL with OpenOffice">
<div class="titlepage">
<div>
<div>
<h1 class="title">
<a name="openoffice-app"></a>HyperSQL with OpenOffice</h1>
</div>
<div>
<h3 class="subtitle">
<i>How to use HyperSQL with OpenOffice.org</i>
</h3>
</div>
<div>
<div class="author">
<h3 class="author">
<span class="firstname">Fred</span> <span class="surname">Toussi</span>
</h3>
<div class="affiliation">
<span class="orgname">The HSQL Development Group<br>
</span>
</div>
</div>
</div>
<div>
<p class="releaseinfo">$Revision: 5051 $</p>
</div>
<div>
<p class="pubdate">2014-02-13 18:21:41-0500</p>
</div>
</div>
</div>
<div class="toc">
<p>
<b>Table of Contents</b>
</p>
<dl>
<dt>
<span class="section"><a href="#ooa_overview">HyperSQL with OpenOffice</a></span>
</dt>
<dt>
<span class="section"><a href="#ooa_database_tool">Using OpenOffice / LibreOffice as a Database Tool</a></span>
</dt>
<dt>
<span class="section"><a href="#ooa_db_files_convert">Converting .odb files to use with HyperSQL Server</a></span>
</dt>
</dl>
</div>
<div class="section" title="HyperSQL with OpenOffice">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="ooa_overview"></a>HyperSQL with OpenOffice</h2>
</div>
</div>
</div>
<p>OpenOffice.org / LibreOffice / ApacheOpenOffice includes HyperSQL
    and uses it for embedded databases. Our collaboration with OpenOffice.org
    developers over the last few years has benefited the development and
    maturity of HyperSQL. Before integration into OOo, HSQLDB was intended
    solely for application-specific database access. The application developer
    was expected to resolve any integration issues. Because OpenOffice.org is
    used by a vast range of users, from schoolchildren to corporate
    developers, a much higher level of quality assurance has been required. We
    have achieved it with constant help and feedback from OOo users and
    developers.</p>
<p>Apart from embedded use, you may want to use OpenOffice /
    LibreOffice with a HyperSQL server instance. The typical use for this is
    to allow multiple office users access to the same database.</p>
<p>There is also a strong case for using OpenOffice to develop your
    database schema and application, even if the database is intended for your
    own application, rather than OpenOffice.</p>
<p>HSQLDB version 1.8.0 is included in OOo, ApacheOpenOffice and
    LibreOffice 3.x. You can simply replace the jar with an HSQLDB version
    2.2.9 jar to use the latest capabilities with external databases. It is
    not yet possible to create and use embedded databases with this
    version.</p>
<p>HSQLDB version 2.x jar will hopefully be included in the future
    versions of ApacheOpenOffice and LibreOffice.</p>
</div>
<div class="section" title="Using OpenOffice / LibreOffice as a Database Tool">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="ooa_database_tool"></a>Using OpenOffice / LibreOffice as a Database Tool</h2>
</div>
</div>
</div>
<p>OpenOffice is a powerful database front end. If you want to
    create schemas, edit tables, edit the database contents manually, design
    and produce well-formatted reports, then OpenOffice is probably the best
    open source tools currently available.</p>
<p>To connect from OpenOffice to your database, first run a local
    server instance for the database. This is describes in the Network
    Listeners chapter of this guide.</p>
<p>When you connect from OpenOffice.org, you must specify connection
    to an external database and use the URL property "default_schema=true".
    For example, the URL to connect the local database may be like</p>
<pre class="programlisting"> jdbc;hsqldb:hsql://localhost/mydb;default_schema=true </pre>
<p>The only current limitation is that OpenOffice only works with
    the PUBLIC schema. This limitation will hopefully disappear in the future
    versions of OOo.</p>
<p>There wil hopefuly be a version 2.x jar in the future versions of
    OpenOffice.</p>
</div>
<div class="section" title="Converting .odb files to use with HyperSQL Server">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both">
<a name="ooa_db_files_convert"></a>Converting .odb files to use with HyperSQL Server</h2>
</div>
</div>
</div>
<p>You may already have an OOo database file, which you want to use
    outside OOo, or as a server database. The file is in fact in the standard
    ZIP format and contains the normal HyperSQL database files. Just use a
    utility such as 7Zip to expand the .odb file. In the /db directory, there
    are files such as .script, .data, etc. Just rename these files into
    mydb.script, mydb.data, etc. You can now open the mydb database directly
    with HyperSQL as an embedded database or as a server instance.</p>
</div>
</div>
<div class="appendix" title="Appendix&nbsp;D.&nbsp;HyperSQL File Links">
<div class="titlepage">
<div>
<div>
<h2 class="title">
<a name="filelinks-app"></a>Appendix&nbsp;D.&nbsp;HyperSQL File Links</h2>
</div>
<div>
<h3 class="subtitle">
<i>HyperSQL Files referred to in this Guide</i>
</h3>
</div>
</div>
</div>
<p>
    HyperSQL files referred to in the text may be retrieved from the
    canonical HyperSQL documentation site, http://hsqldb.org/doc/2.0, or from the
    same location you are reading this page from.
  </p>
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
<table border="0" summary="Note">
<tr>
<td valign="top" align="center" rowspan="2" width="25"><img alt="[Note]" src="../images/db/note.png"></td><th align="left">Note</th>
</tr>
<tr>
<td valign="top" align="left">
<p>
    If you are reading this document with a standalone PDF reader,
    only the http://hsqldb.org/doc/2.0/... links will function.
  </p>
</td>
</tr>
</table>
</div>
<div class="itemizedlist" title="Pairs of local + http://hsqldb.org/doc/2.0 links for referenced files.">
<p class="title">
<b>
      Pairs of local + http://hsqldb.org/doc/2.0 links for referenced files.
    </b>
</p>
<ul class="itemizedlist" type="disc">
<li class="listitem">
<a name="JDBCConnection.html-link"></a>
<p class="simpara">
        Local:
        <a class="link" href="../apidocs/org/hsqldb/jdbc/JDBCConnection.html" target="_top">../apidocs/org/hsqldb/jdbc/JDBCConnection.html</a>
      
</p>
<p class="simpara">
        
<a class="link" href="http://hsqldb.org/doc/2.0/apidocs/org/hsqldb/jdbc/JDBCConnection.html" target="_top">http://hsqldb.org/doc/2.0/apidocs/org/hsqldb/jdbc/JDBCConnection.html</a>
      
</p>
</li>
<li class="listitem">
<a name="JDBCDriver.html-link"></a>
<p class="simpara">
        Local:
        <a class="link" href="../apidocs/org/hsqldb/jdbc/JDBCDriver.html" target="_top">../apidocs/org/hsqldb/jdbc/JDBCDriver.html</a>
      
</p>
<p class="simpara">
        
<a class="link" href="http://hsqldb.org/doc/2.0/apidocs/org/hsqldb/jdbc/JDBCDriver.html" target="_top">http://hsqldb.org/doc/2.0/apidocs/org/hsqldb/jdbc/JDBCDriver.html</a>
      
</p>
</li>
<li class="listitem">
<a name="JDBCDatabaseMetaData.html-link"></a>
<p class="simpara">
        Local:
        <a class="link" href="../apidocs/org/hsqldb/jdbc/JDBCDatabaseMetaData.html" target="_top">../apidocs/org/hsqldb/jdbc/JDBCDatabaseMetaData.html</a>
      
</p>
<p class="simpara">
        
<a class="link" href="http://hsqldb.org/doc/2.0/apidocs/org/hsqldb/jdbc/JDBCDatabaseMetaData.html" target="_top">http://hsqldb.org/doc/2.0/apidocs/org/hsqldb/jdbc/JDBCDatabaseMetaData.html</a>
      
</p>
</li>
<li class="listitem">
<a name="JDBCResultSet.html-link"></a>
<p class="simpara">
        Local:
        <a class="link" href="../apidocs/org/hsqldb/jdbc/JDBCResultSet.html" target="_top">../apidocs/org/hsqldb/jdbc/JDBCResultSet.html</a>
      
</p>
<p class="simpara">
        
<a class="link" href="http://hsqldb.org/doc/2.0/apidocs/org/hsqldb/jdbc/JDBCResultSet.html" target="_top">http://hsqldb.org/doc/2.0/apidocs/org/hsqldb/jdbc/JDBCResultSet.html</a>
      
</p>
</li>
<li class="listitem">
<a name="JDBCStatement.html-link"></a>
<p class="simpara">
        Local:
        <a class="link" href="../apidocs/org/hsqldb/jdbc/JDBCStatement.html" target="_top">../apidocs/org/hsqldb/jdbc/JDBCStatement.html</a>
      
</p>
<p class="simpara">
        
<a class="link" href="http://hsqldb.org/doc/2.0/apidocs/org/hsqldb/jdbc/JDBCStatement.html" target="_top">http://hsqldb.org/doc/2.0/apidocs/org/hsqldb/jdbc/JDBCStatement.html</a>
      
</p>
</li>
<li class="listitem">
<a name="JDBCPreparedStatement.html-link"></a>
<p class="simpara">
        Local:
        <a class="link" href="../apidocs/org/hsqldb/jdbc/JDBCPreparedStatement.html" target="_top">../apidocs/org/hsqldb/jdbc/JDBCPreparedStatement.html</a>
      
</p>
<p class="simpara">
        
<a class="link" href="http://hsqldb.org/doc/2.0/apidocs/org/hsqldb/jdbc/JDBCPreparedStatement.html" target="_top">http://hsqldb.org/doc/2.0/apidocs/org/hsqldb/jdbc/JDBCPreparedStatement.html</a>
      
</p>
</li>
<li class="listitem">
<a name="MainInvoker.html-link"></a>
<p class="simpara">
        Local:
        <a class="link" href="../apidocs/org/hsqldb/util/MainInvoker.html" target="_top">../apidocs/org/hsqldb/util/MainInvoker.html</a>
      
</p>
<p class="simpara">
      
<a class="link" href="http://hsqldb.org/doc/2.0/apidocs/org/hsqldb/util/MainInvoker.html" target="_top">http://hsqldb.org/doc/2.0/apidocs/org/hsqldb/util/MainInvoker.html</a>
      
</p>
</li>
<li class="listitem">
<a name="javadoc-link"></a>
<p class="simpara">
        Local:
        <a class="link" href="../apidocs/index.html" target="_top">../apidocs/index.html</a>
      
</p>
<p class="simpara">
        
<a class="link" href="http://hsqldb.org/doc/2.0/apidocs/" target="_top">http://hsqldb.org/doc/2.0/apidocs/</a>
      
</p>
</li>
<li class="listitem">
<a name="Servlet.java-link"></a>
<p class="simpara">
        Local:
        <a class="link" href="../verbatim/src/org/hsqldb/server/Servlet.java" target="_top">../verbatim/src/org/hsqldb/server/Servlet.java</a>
      
</p>
<p class="simpara">
        
<a class="link" href="http://hsqldb.org/doc/2.0/verbatim/src/org/hsqldb/server/Servlet.java" target="_top">http://hsqldb.org/doc/2.0/verbatim/src/org/hsqldb/server/Servlet.java</a>
      
</p>
</li>
<li class="listitem">
<a name="Tokens.java-link"></a>
<p class="simpara">
        Local:
        <a class="link" href="../verbatim/src/org/hsqldb/Tokens.java" target="_top">../verbatim/src/org/hsqldb/Tokens.java</a>
      
</p>
<p class="simpara">
        
<a class="link" href="http://hsqldb.org/doc/2.0/verbatim/src/org/hsqldb/Tokens.java" target="_top">http://hsqldb.org/doc/2.0/verbatim/src/org/hsqldb/Tokens.java</a>
      
</p>
</li>
<li class="listitem">
<a name="WebServer.java-link"></a>
<p class="simpara">
        Local:
        <a class="link" href="../verbatim/src/org/hsqldb/server/WebServer.java" target="_top">../verbatim/src/org/hsqldb/server/WebServer.java</a>
      
</p>
<p class="simpara">
        
<a class="link" href="http://hsqldb.org/doc/2.0/verbatim/src/org/hsqldb/server/WebServer.java" target="_top">http://hsqldb.org/doc/2.0/verbatim/src/org/hsqldb/server/WebServer.java</a>
      
</p>
</li>
<li class="listitem">
<a name="TestBase.java-link"></a>
<p class="simpara">
        Local:
        <a class="link" href="../verbatim/src/org/hsqldb/test/TestBase.java" target="_top">../verbatim/src/org/hsqldb/test/TestBase.java</a>
      
</p>
<p class="simpara">
        
<a class="link" href="http://hsqldb.org/doc/2.0/verbatim/src/org/hsqldb/test/TestBase.java" target="_top">http://hsqldb.org/doc/2.0/verbatim/src/org/hsqldb/test/TestBase.java</a>
      
</p>
</li>
<li class="listitem">
<a name="Trigger.java-link"></a>
<p class="simpara">
        Local:
        <a class="link" href="../verbatim/src/org/hsqldb/Trigger.java" target="_top">../verbatim/src/org/hsqldb/Trigger.java</a>
      
</p>
<p class="simpara">
        
<a class="link" href="http://hsqldb.org/doc/2.0/verbatim/src/org/hsqldb/Trigger.java" target="_top">http://hsqldb.org/doc/2.0/verbatim/src/org/hsqldb/Trigger.java</a>
      
</p>
</li>
<li class="listitem">
<a name="TriggerSample.java-link"></a>
<p class="simpara">
        Local:
        <a class="link" href="../verbatim/src/org/hsqldb/sample/TriggerSample.java" target="_top">../verbatim/src/org/hsqldb/sample/TriggerSample.java</a>
      
</p>
<p class="simpara">
        
<a class="link" href="http://hsqldb.org/doc/2.0/verbatim/src/org/hsqldb/test/sample/TriggerSample.java" target="_top">http://hsqldb.org/doc/2.0/verbatim/src/org/hsqldb/test/sample/TriggerSample.java</a>
      
</p>
</li>
<li class="listitem">
<a name="MainInvoker.java-link"></a>
<p class="simpara">
        Local:
        <a class="link" href="../verbatim/src/org/hsqldb/util/MainInvoker.java" target="_top">../verbatim/src/org/hsqldb/util/MainInvoker.java</a>
      
</p>
<p class="simpara">
      
<a class="link" href="http://hsqldb.org/doc/2.0/verbatim/src/org/hsqldb/util/MainInvoker.java" target="_top">http://hsqldb.org/doc/2.0/verbatim/src/org/hsqldb/util/MainInvoker.java</a>
      
</p>
</li>
<li class="listitem">
<a name="hsqldb.cfg-link"></a>
<p class="simpara">
        Local:
        <a class="link" href="../verbatim/sample/hsqldb.cfg" target="_top">../verbatim/sample/hsqldb.cfg</a>
      
</p>
<p class="simpara">
        
<a class="link" href="http://hsqldb.org/doc/2.0/verbatim/sample/hsqldb.cfg" target="_top">http://hsqldb.org/doc/2.0/verbatim/sample/hsqldb.cfg</a>
      
</p>
</li>
<li class="listitem">
<a name="acl.txt-link"></a>
<p class="simpara">
        Local:
        <a class="link" href="../verbatim/sample/acl.txt" target="_top">../verbatim/sample/acl.txt</a>
      
</p>
<p class="simpara">
        
<a class="link" href="http://hsqldb.org/doc/2.0/verbatim/sample/acl.txt" target="_top">http://hsqldb.org/doc/2.0/verbatim/sample/acl.txt</a>
      
</p>
</li>
<li class="listitem">
<a name="server.properties-link"></a>
<p class="simpara">
        Local:
        <a class="link" href="../verbatim/sample/server.properties" target="_top">../verbatim/sample/server.properties</a>
      
</p>
<p class="simpara">
        
<a class="link" href="http://hsqldb.org/doc/2.0/verbatim/sample/server.properties" target="_top">http://hsqldb.org/doc/2.0/verbatim/sample/server.properties</a>
      
</p>
</li>
<li class="listitem">
<a name="sqltool.rc-link"></a>
<p class="simpara">
        Local:
        <a class="link" href="../verbatim/sample/sqltool.rc" target="_top">../verbatim/sample/sqltool.rc</a>
      
</p>
<p class="simpara">
        
<a class="link" href="http://hsqldb.org/doc/2.0/verbatim/sample/sqltool.rc" target="_top">http://hsqldb.org/doc/2.0/verbatim/sample/sqltool.rc</a>
      
</p>
</li>
<li class="listitem">
<a name="hsqldb.init-link"></a>
<p class="simpara">
        Local:
        <a class="link" href="../verbatim/sample/hsqldb.init" target="_top">../verbatim/sample/hsqldb.init</a>
      
</p>
<p class="simpara">
        
<a class="link" href="http://hsqldb.org/doc/2.0/verbatim/sample/hsqldb.init" target="_top">http://hsqldb.org/doc/2.0/verbatim/sample/hsqldb.init</a>
      
</p>
</li>
</ul>
</div>
</div>
<div class="index" title="SQL Index">
<div class="titlepage">
<div>
<div>
<h2 class="title">
<a name="sql-ind"></a>SQL Index</h2>
</div>
</div>
</div>
<div class="index">
<div class="indexdiv">
<h3>Symbols</h3>
<dl>
<dt>_SYSTEM ROLE, <a class="indexterm" href="#acc_built_in_roles_users">Built-In Roles and Users</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>A</h3>
<dl>
<dt>ABS function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>ACOS function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>ACTION_ID function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>ADD_MONTHS function, <a class="indexterm" href="#bfc_datetime_arithmetic">Functions for Datetime Arithmetic</a>
</dt>
<dt>ADD COLUMN, <a class="indexterm" href="#dbc_table_manupulation">Table Manipulation</a>
</dt>
<dt>add column identity generator, <a class="indexterm" href="#dbc_table_manupulation">Table Manipulation</a>
</dt>
<dt>ADD CONSTRAINT, <a class="indexterm" href="#dbc_table_manupulation">Table Manipulation</a>
</dt>
<dt>ADD DOMAIN CONSTRAINT, <a class="indexterm" href="#dbc_domain_creation">Domain Creation and Manipulation</a>
</dt>
<dt>ADMINISTRABLE_ROLE_AUTHORIZATIONS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>aggregate function, <a class="indexterm" href="#dac_aggregate_funcs">Aggregate Functions</a>
</dt>
<dt>ALL and ANY predicates, <a class="indexterm" href="#dac_sql_predicates">Predicates</a>
</dt>
<dt>ALTER COLUMN, <a class="indexterm" href="#dbc_table_manupulation">Table Manipulation</a>
</dt>
<dt>alter column identity generator, <a class="indexterm" href="#dbc_table_manupulation">Table Manipulation</a>
</dt>
<dt>alter column nullability, <a class="indexterm" href="#dbc_table_manupulation">Table Manipulation</a>
</dt>
<dt>ALTER DOMAIN, <a class="indexterm" href="#dbc_domain_creation">Domain Creation and Manipulation</a>
</dt>
<dt>ALTER INDEX, <a class="indexterm" href="#dbc_other_object_creation">Other Schema Object Creation</a>
</dt>
<dt>ALTER routine, <a class="indexterm" href="#dbc_routine_creation">Routine Creation</a>
</dt>
<dt>ALTER SEQUENCE, <a class="indexterm" href="#dbc_sequence_creation">Sequence Creation</a>
</dt>
<dt>ALTER SESSION, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>ALTER TABLE, <a class="indexterm" href="#dbc_table_manupulation">Table Manipulation</a>
</dt>
<dt>ALTER USER ... SET INITIAL SCHEMA, <a class="indexterm" href="#acc_statements">Statements for
    Authorization and Access Control</a>
</dt>
<dt>ALTER USER ... SET LOCAL, <a class="indexterm" href="#acc_statements">Statements for
    Authorization and Access Control</a>
</dt>
<dt>ALTER USER ... SET PASSWORD, <a class="indexterm" href="#acc_statements">Statements for
    Authorization and Access Control</a>
</dt>
<dt>ALTER view, <a class="indexterm" href="#dbc_view_creation">View Creation and Manipulation</a>
</dt>
<dt>APPLICABLE_ROLES, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>ASCII function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>ASIN function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>ASSERTIONS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>ATAN2 function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>ATAN function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>AUTHORIZATION IDENTIFIER, <a class="indexterm" href="#acc_auth_and_access_ctrl">Authorizations and Access Control</a>
</dt>
<dt>AUTHORIZATIONS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>B</h3>
<dl>
<dt>BACKUP DATABASE, <a class="indexterm" href="#mtc_system_operations">System Operations</a>
</dt>
<dt>BETWEEN predicate, <a class="indexterm" href="#dac_sql_predicates">Predicates</a>
</dt>
<dt>binary literal, <a class="indexterm" href="#dac_literals">Literals</a>
</dt>
<dt>BINARY types, <a class="indexterm" href="#sgc_binary_types">Binary String Types</a>
</dt>
<dt>BIT_LENGTH function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>BITAND function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>BITANDNOT function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>bit literal, <a class="indexterm" href="#dac_literals">Literals</a>
</dt>
<dt>BITNOT function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>BITOR function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>BIT types, <a class="indexterm" href="#sgc_bit_types">Bit String Types</a>
</dt>
<dt>BITXOR function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>boolean literal, <a class="indexterm" href="#dac_literals">Literals</a>
</dt>
<dt>BOOLEAN types, <a class="indexterm" href="#sgc_boolean_type">Boolean Type</a>
</dt>
<dt>boolean value expression, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>C</h3>
<dl>
<dt>CARDINALITY function, <a class="indexterm" href="#bfc_array_functions">Array Functions</a>
</dt>
<dt>CASCADE or RESTRICT, <a class="indexterm" href="#dbc_common_elements">Common Elements and Statements</a>
</dt>
<dt>case expression, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
<dt>CASEWHEN function, <a class="indexterm" href="#bfc_general_functions">General Functions</a>
</dt>
<dt>CASE WHEN in routines, <a class="indexterm" href="#src_psm_conditional">Conditional Statements</a>
</dt>
<dt>CAST, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
<dt>CEIL function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>CHANGE_AUTHORIZATION, <a class="indexterm" href="#acc_built_in_roles_users">Built-In Roles and Users</a>
</dt>
<dt>CHAR_LENGTH, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>CHARACTER_LENGTH, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>CHARACTER_SETS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>character literal, <a class="indexterm" href="#dac_literals">Literals</a>
</dt>
<dt>CHARACTER types, <a class="indexterm" href="#sgc_char_types">Character String Types</a>
</dt>
<dt>character value function, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
<dt>CHAR function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>CHECK_CONSTRAINT_ROUTINE_USAGE, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>CHECK_CONSTRAINTS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>CHECK constraint, <a class="indexterm" href="#dbc_table_creation">Table Creation</a>
</dt>
<dt>CHECKPOINT, <a class="indexterm" href="#mtc_system_operations">System Operations</a>
</dt>
<dt>COALESCE expression, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
<dt>COALESCE function, <a class="indexterm" href="#bfc_general_functions">General Functions</a>
</dt>
<dt>COLLATE, <a class="indexterm" href="#dac_other_syntax_elements">Other Syntax Elements</a>
</dt>
<dt>COLLATIONS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>COLUMN_COLUMN_USAGE, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>COLUMN_DOMAIN_USAGE, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>COLUMN_PRIVILEGES, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>COLUMN_UDT_USAGE, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>column definition, <a class="indexterm" href="#dbc_table_creation">Table Creation</a>
</dt>
<dt>column name list, <a class="indexterm" href="#dac_col_name_list">Column Name List</a>
</dt>
<dt>column reference, <a class="indexterm" href="#dac_sql_references">References, etc.</a>
</dt>
<dt>COLUMNS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>COMMENT, <a class="indexterm" href="#dbc_commenting">Commenting Objects</a>
</dt>
<dt>COMMIT, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>comparison predicate, <a class="indexterm" href="#dac_sql_predicates">Predicates</a>
</dt>
<dt>CONCAT_WS function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>CONCAT function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>CONSTRAINT, <a class="indexterm" href="#dac_other_syntax_elements">Other Syntax Elements</a>
</dt>
<dt>CONSTRAINT_COLUMN_USAGE, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>CONSTRAINT_TABLE_USAGE, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>CONSTRAINT (table constraint), <a class="indexterm" href="#dbc_table_creation">Table Creation</a>
</dt>
<dt>CONSTRAINT name and characteristics, <a class="indexterm" href="#dbc_table_creation">Table Creation</a>
</dt>
<dt>contextually typed value specification, <a class="indexterm" href="#dac_sql_references">References, etc.</a>
</dt>
<dt>CONVERT function, <a class="indexterm" href="#bfc_general_functions">General Functions</a>
</dt>
<dt>COS function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>COT function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>CREATE_SCHEMA ROLE, <a class="indexterm" href="#acc_built_in_roles_users">Built-In Roles and Users</a>
</dt>
<dt>CREATE AGGREGATE FUNCTION, <a class="indexterm" href="#src_aggregate_function_definition">Definition of Aggregate Functions</a>
</dt>
<dt>CREATE ASSERTION, <a class="indexterm" href="#dbc_other_object_creation">Other Schema Object Creation</a>
</dt>
<dt>CREATE CAST, <a class="indexterm" href="#dbc_other_object_creation">Other Schema Object Creation</a>
</dt>
<dt>CREATE CHARACTER SET, <a class="indexterm" href="#dbc_other_object_creation">Other Schema Object Creation</a>
</dt>
<dt>CREATE COLLATION, <a class="indexterm" href="#dbc_other_object_creation">Other Schema Object Creation</a>
</dt>
<dt>CREATE DOMAIN, <a class="indexterm" href="#dbc_domain_creation">Domain Creation and Manipulation</a>
</dt>
<dt>CREATE FUNCTION, <a class="indexterm" href="#src_routine_definition">Routine Definition</a>
</dt>
<dt>CREATE INDEX, <a class="indexterm" href="#dbc_other_object_creation">Other Schema Object Creation</a>
</dt>
<dt>CREATE PROCEDURE, <a class="indexterm" href="#src_routine_definition">Routine Definition</a>
</dt>
<dt>CREATE ROLE, <a class="indexterm" href="#acc_statements">Statements for
    Authorization and Access Control</a>
</dt>
<dt>CREATE SCHEMA, <a class="indexterm" href="#dbc_schema_creation">Schema Creation</a>
</dt>
<dt>CREATE SEQUENCE, <a class="indexterm" href="#dbc_sequence_creation">Sequence Creation</a>
</dt>
<dt>CREATE TABLE, <a class="indexterm" href="#dbc_table_creation">Table Creation</a>
</dt>
<dt>CREATE TRANSLATION, <a class="indexterm" href="#dbc_other_object_creation">Other Schema Object Creation</a>
</dt>
<dt>CREATE TRIGGER, <a class="indexterm" href="#dbc_trigger_creation">Trigger Creation</a>, <a class="indexterm" href="#trc_trigger_creation">Trigger Creation</a>
</dt>
<dt>CREATE TYPE, <a class="indexterm" href="#dbc_other_object_creation">Other Schema Object Creation</a>
</dt>
<dt>CREATE USER, <a class="indexterm" href="#acc_statements">Statements for
    Authorization and Access Control</a>
</dt>
<dt>CREATE VIEW, <a class="indexterm" href="#dbc_view_creation">View Creation and Manipulation</a>
</dt>
<dt>CROSS JOIN, <a class="indexterm" href="#dac_joined_table">Joined Table</a>
</dt>
<dt>CRYPT_KEY function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>CURDATE function, <a class="indexterm" href="#bfc_current_datetime">Functions to Report the Current Datetime</a>
</dt>
<dt>CURRENT_CATALOG function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>CURRENT_DATE function, <a class="indexterm" href="#bfc_current_datetime">Functions to Report the Current Datetime</a>
</dt>
<dt>CURRENT_ROLE function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>CURRENT_SCHEMA function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>CURRENT_TIME function, <a class="indexterm" href="#bfc_current_datetime">Functions to Report the Current Datetime</a>
</dt>
<dt>CURRENT_TIMESTAMP function, <a class="indexterm" href="#bfc_current_datetime">Functions to Report the Current Datetime</a>
</dt>
<dt>CURRENT_USER function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>CURRENT VALUE FOR, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
<dt>CURTIME function, <a class="indexterm" href="#bfc_current_datetime">Functions to Report the Current Datetime</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>D</h3>
<dl>
<dt>DATA_TYPE_PRIVILEGES, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>DATABASE_ISOLATION_LEVEL function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>DATABASE_NAME function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>DATABASE_TIMEZONE function, <a class="indexterm" href="#bfc_timezone_functions">Functions to Report the Time Zone.</a>
</dt>
<dt>DATABASE_VERSION function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>DATABASE function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>DATE_ADD function, <a class="indexterm" href="#bfc_datetime_arithmetic">Functions for Datetime Arithmetic</a>
</dt>
<dt>DATE_SUB function, <a class="indexterm" href="#bfc_datetime_arithmetic">Functions for Datetime Arithmetic</a>
</dt>
<dt>DATEADD function, <a class="indexterm" href="#bfc_datetime_arithmetic">Functions for Datetime Arithmetic</a>
</dt>
<dt>DATEDIFF function, <a class="indexterm" href="#bfc_datetime_arithmetic">Functions for Datetime Arithmetic</a>
</dt>
<dt>datetime and interval literal, <a class="indexterm" href="#dac_literals">Literals</a>
</dt>
<dt>Datetime Operations, <a class="indexterm" href="#sgc_datetime_types">Datetime types</a>
</dt>
<dt>DATETIME types, <a class="indexterm" href="#sgc_datetime_types">Datetime types</a>
</dt>
<dt>datetime value expression, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
<dt>datetime value function, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
<dt>DAYNAME function, <a class="indexterm" href="#bfc_extract_datetime">Functions to Extract an Element of a Datetime</a>
</dt>
<dt>DAYOFMONTH function, <a class="indexterm" href="#bfc_extract_datetime">Functions to Extract an Element of a Datetime</a>
</dt>
<dt>DAYOFWEEK function, <a class="indexterm" href="#bfc_extract_datetime">Functions to Extract an Element of a Datetime</a>
</dt>
<dt>DAYOFYEAR function, <a class="indexterm" href="#bfc_extract_datetime">Functions to Extract an Element of a Datetime</a>
</dt>
<dt>DAYS function datetime, <a class="indexterm" href="#bfc_extract_datetime">Functions to Extract an Element of a Datetime</a>
</dt>
<dt>DBA ROLE, <a class="indexterm" href="#acc_built_in_roles_users">Built-In Roles and Users</a>
</dt>
<dt>DECLARE CURSOR, <a class="indexterm" href="#dac_declare_cursor">Cursor Declaration</a>
</dt>
<dt>DECLARE HANDLER, <a class="indexterm" href="#src_psm_handlers">Handlers</a>
</dt>
<dt>DECLARE variable, <a class="indexterm" href="#src_psm_vars">Variables</a>
</dt>
<dt>DECODE function, <a class="indexterm" href="#bfc_general_functions">General Functions</a>
</dt>
<dt>DEFAULT clause, <a class="indexterm" href="#dbc_table_creation">Table Creation</a>
</dt>
<dt>DEGREES function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>DELETE FROM, <a class="indexterm" href="#dac_delete_statement">Delete Statement</a>
</dt>
<dt>derived table, <a class="indexterm" href="#dac_derived_table">Derived Table</a>
</dt>
<dt>DETERMINISTIC characteristic, <a class="indexterm" href="#src_routine_characteristics">Routine Characteristics</a>
</dt>
<dt>DIAGNOSTICS function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>DIFFERENCE function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>DISCONNECT, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>DISTINCT, <a class="indexterm" href="#dac_grouping_operations">Grouping Operations</a>
</dt>
<dt>DOMAIN_CONSTRAINTS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>DOMAINS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>DROP ASSERTION, <a class="indexterm" href="#dbc_other_object_creation">Other Schema Object Creation</a>
</dt>
<dt>DROP CAST, <a class="indexterm" href="#dbc_other_object_creation">Other Schema Object Creation</a>
</dt>
<dt>DROP CHARACTER SET, <a class="indexterm" href="#dbc_other_object_creation">Other Schema Object Creation</a>
</dt>
<dt>DROP COLLATION, <a class="indexterm" href="#dbc_other_object_creation">Other Schema Object Creation</a>
</dt>
<dt>DROP COLUMN, <a class="indexterm" href="#dbc_table_manupulation">Table Manipulation</a>
</dt>
<dt>drop column idenitty generator, <a class="indexterm" href="#dbc_table_manupulation">Table Manipulation</a>
</dt>
<dt>DROP CONSTRAINT, <a class="indexterm" href="#dbc_table_manupulation">Table Manipulation</a>
</dt>
<dt>DROP DEFAULT (table), <a class="indexterm" href="#dbc_table_manupulation">Table Manipulation</a>
</dt>
<dt>DROP DOMAIN, <a class="indexterm" href="#dbc_domain_creation">Domain Creation and Manipulation</a>
</dt>
<dt>DROP DOMAIN CONSTRAINT, <a class="indexterm" href="#dbc_domain_creation">Domain Creation and Manipulation</a>
</dt>
<dt>DROP DOMAIN DEFAULT, <a class="indexterm" href="#dbc_domain_creation">Domain Creation and Manipulation</a>
</dt>
<dt>DROP INDEX, <a class="indexterm" href="#dbc_other_object_creation">Other Schema Object Creation</a>
</dt>
<dt>DROP ROLE, <a class="indexterm" href="#acc_statements">Statements for
    Authorization and Access Control</a>
</dt>
<dt>DROP routine, <a class="indexterm" href="#dbc_routine_creation">Routine Creation</a>
</dt>
<dt>DROP SCHEMA, <a class="indexterm" href="#dbc_schema_creation">Schema Creation</a>
</dt>
<dt>DROP SEQUENCE, <a class="indexterm" href="#dbc_sequence_creation">Sequence Creation</a>
</dt>
<dt>DROP TABLE, <a class="indexterm" href="#dbc_table_creation">Table Creation</a>
</dt>
<dt>DROP TRANSLATION, <a class="indexterm" href="#dbc_other_object_creation">Other Schema Object Creation</a>
</dt>
<dt>DROP TRIGGER, <a class="indexterm" href="#dbc_trigger_creation">Trigger Creation</a>, <a class="indexterm" href="#trc_trigger_creation">Trigger Creation</a>
</dt>
<dt>DROP USER, <a class="indexterm" href="#acc_statements">Statements for
    Authorization and Access Control</a>
</dt>
<dt>DROP VIEW, <a class="indexterm" href="#dbc_view_creation">View Creation and Manipulation</a>
</dt>
<dt>DYNAMIC RESULT SETS, <a class="indexterm" href="#src_routine_characteristics">Routine Characteristics</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>E</h3>
<dl>
<dt>ELEMENT_TYPES, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>ENABLED_ROLES, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>EXISTS predicate, <a class="indexterm" href="#dac_sql_predicates">Predicates</a>
</dt>
<dt>EXP function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>expression, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
<dt>external authentication, <a class="indexterm" href="#mtc_authentication_control">Authentication Control</a>
</dt>
<dt>EXTERNAL NAME, <a class="indexterm" href="#src_routine_definition">Routine Definition</a>
</dt>
<dt>EXTRACT function, <a class="indexterm" href="#bfc_extract_datetime">Functions to Extract an Element of a Datetime</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>F</h3>
<dl>
<dt>FLOOR function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>FOREIGN KEY constraint, <a class="indexterm" href="#dbc_table_creation">Table Creation</a>
</dt>
<dt>FOR loop in routines, <a class="indexterm" href="#src_psm_for_statement">Iterated FOR Statement</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>G</h3>
<dl>
<dt>generated column specification, <a class="indexterm" href="#dbc_table_creation">Table Creation</a>
</dt>
<dt>GET DIAGNOSTICS, <a class="indexterm" href="#dac_diagnostics_state">Diagnostics and State</a>
</dt>
<dt>GRANTED BY, <a class="indexterm" href="#acc_statements">Statements for
    Authorization and Access Control</a>
</dt>
<dt>GRANT privilege, <a class="indexterm" href="#acc_statements">Statements for
    Authorization and Access Control</a>
</dt>
<dt>GRANT role, <a class="indexterm" href="#acc_statements">Statements for
    Authorization and Access Control</a>
</dt>
<dt>GREATEST function, <a class="indexterm" href="#bfc_general_functions">General Functions</a>
</dt>
<dt>GROUP BY, <a class="indexterm" href="#dac_grouping_operations">Grouping Operations</a>
</dt>
<dt>GROUPING OPERATIONS, <a class="indexterm" href="#dac_grouping_operations">Grouping Operations</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>H</h3>
<dl>
<dt>HEXTORAW function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>HOUR function, <a class="indexterm" href="#bfc_extract_datetime">Functions to Extract an Element of a Datetime</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>I</h3>
<dl>
<dt>identifier chain, <a class="indexterm" href="#dac_sql_references">References, etc.</a>
</dt>
<dt>identifier definition, <a class="indexterm" href="#dbc_common_elements">Common Elements and Statements</a>
</dt>
<dt>IDENTITY function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>IF EXISTS, <a class="indexterm" href="#dbc_common_elements">Common Elements and Statements</a>
</dt>
<dt>IFNULL function, <a class="indexterm" href="#bfc_general_functions">General Functions</a>
</dt>
<dt>IF STATEMENT, <a class="indexterm" href="#src_psm_conditional">Conditional Statements</a>
</dt>
<dt>INFORMATION_SCHEMA_CATALOG_NAME, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>IN predicate, <a class="indexterm" href="#dac_sql_predicates">Predicates</a>
</dt>
<dt>INSERT function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>INSERT INTO, <a class="indexterm" href="#dac_insert_statement">Insert Statement</a>
</dt>
<dt>INSTR function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>interval absolute value function, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
<dt>interval term, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
<dt>INTERVAL types, <a class="indexterm" href="#sgc_interval_typs">Interval Types</a>
</dt>
<dt>IS_AUTOCOMMIT function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>IS_READONLY_DATABASE_FILES function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>IS_READONLY_DATABASE function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>IS_READONLY_SESSION function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>IS DISTINCT predicate, <a class="indexterm" href="#dac_sql_predicates">Predicates</a>
</dt>
<dt>ISNULL function, <a class="indexterm" href="#bfc_general_functions">General Functions</a>
</dt>
<dt>IS NULL predicate, <a class="indexterm" href="#dac_sql_predicates">Predicates</a>
</dt>
<dt>ISOLATION_LEVEL function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>J</h3>
<dl>
<dt>JOIN USING, <a class="indexterm" href="#dac_joined_table">Joined Table</a>
</dt>
<dt>JOIN with condition, <a class="indexterm" href="#dac_joined_table">Joined Table</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>K</h3>
<dl>
<dt>KEY_COLUMN_USAGE, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>L</h3>
<dl>
<dt>LANGUAGE, <a class="indexterm" href="#src_routine_characteristics">Routine Characteristics</a>
</dt>
<dt>LAST_DAY function, <a class="indexterm" href="#bfc_datetime_arithmetic">Functions for Datetime Arithmetic</a>
</dt>
<dt>LATERAL, <a class="indexterm" href="#dac_lateral">Lateral</a>
</dt>
<dt>LCASE function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>LEAST function, <a class="indexterm" href="#bfc_general_functions">General Functions</a>
</dt>
<dt>LEFT function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>LENGTH function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>LIKE predicate, <a class="indexterm" href="#dac_sql_predicates">Predicates</a>
</dt>
<dt>LN function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>LOAD_FILE function, <a class="indexterm" href="#bfc_general_functions">General Functions</a>
</dt>
<dt>LOB_ID function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>LOCALTIME function, <a class="indexterm" href="#bfc_current_datetime">Functions to Report the Current Datetime</a>
</dt>
<dt>LOCALTIMESTAMP function, <a class="indexterm" href="#bfc_current_datetime">Functions to Report the Current Datetime</a>
</dt>
<dt>LOCATE function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>LOCK TABLE, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>LOG10 function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>LOG function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>LOOP in routines, <a class="indexterm" href="#src_psm_iterated_statements">Iterated Statements</a>
</dt>
<dt>LPAD function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>LTRIM function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>M</h3>
<dl>
<dt>MATCH predicate, <a class="indexterm" href="#dac_sql_predicates">Predicates</a>
</dt>
<dt>MAX_CARDINALITY function, <a class="indexterm" href="#bfc_array_functions">Array Functions</a>
</dt>
<dt>MERGE INTO, <a class="indexterm" href="#dac_merge_statement">Merge Statement</a>
</dt>
<dt>MINUTE function, <a class="indexterm" href="#bfc_extract_datetime">Functions to Extract an Element of a Datetime</a>
</dt>
<dt>MOD function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>MONTH function, <a class="indexterm" href="#bfc_extract_datetime">Functions to Extract an Element of a Datetime</a>
</dt>
<dt>MONTHNAME function, <a class="indexterm" href="#bfc_extract_datetime">Functions to Extract an Element of a Datetime</a>
</dt>
<dt>MONTHS_BETWEEN function, <a class="indexterm" href="#bfc_datetime_arithmetic">Functions for Datetime Arithmetic</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>N</h3>
<dl>
<dt>name resolution, <a class="indexterm" href="#dac_naming">Naming</a>
</dt>
<dt>naming in joined table, <a class="indexterm" href="#dac_naming">Naming</a>
</dt>
<dt>naming in select list, <a class="indexterm" href="#dac_naming">Naming</a>
</dt>
<dt>NATURAL JOIN, <a class="indexterm" href="#dac_joined_table">Joined Table</a>
</dt>
<dt>NEXT VALUE FOR, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
<dt>NOW function, <a class="indexterm" href="#bfc_current_datetime">Functions to Report the Current Datetime</a>
</dt>
<dt>NULLIF function, <a class="indexterm" href="#bfc_general_functions">General Functions</a>
</dt>
<dt>NULL INPUT, <a class="indexterm" href="#src_routine_characteristics">Routine Characteristics</a>
</dt>
<dt>numeric literal, <a class="indexterm" href="#dac_literals">Literals</a>
</dt>
<dt>NUMERIC types, <a class="indexterm" href="#sgc_numeric_types">Numeric Types</a>
</dt>
<dt>numeric value expression, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
<dt>numeric value function, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
<dt>NVL2 function, <a class="indexterm" href="#bfc_general_functions">General Functions</a>
</dt>
<dt>NVL function, <a class="indexterm" href="#bfc_general_functions">General Functions</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>O</h3>
<dl>
<dt>OCTET_LENGTH function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>OTHER type, <a class="indexterm" href="#sgc_java_objects">Storage and Handling of Java Objects</a>
</dt>
<dt>OUTER JOIN, <a class="indexterm" href="#dac_joined_table">Joined Table</a>
</dt>
<dt>OVERLAPS predicate, <a class="indexterm" href="#dac_sql_predicates">Predicates</a>
</dt>
<dt>OVERLAY function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>P</h3>
<dl>
<dt>PARAMETERS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>password complexity, <a class="indexterm" href="#mtc_authentication_control">Authentication Control</a>
</dt>
<dt>PATH, <a class="indexterm" href="#dac_other_syntax_elements">Other Syntax Elements</a>
</dt>
<dt>PI function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>POSITION_ARRAY function, <a class="indexterm" href="#bfc_array_functions">Array Functions</a>
</dt>
<dt>POSITION function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>POWER function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>PRIMARY KEY constraint, <a class="indexterm" href="#dbc_table_creation">Table Creation</a>
</dt>
<dt>PUBLIC ROLE, <a class="indexterm" href="#acc_built_in_roles_users">Built-In Roles and Users</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>Q</h3>
<dl>
<dt>QUARTER function, <a class="indexterm" href="#bfc_extract_datetime">Functions to Extract an Element of a Datetime</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>R</h3>
<dl>
<dt>RADIANS function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>RAND function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>RAWTOHEX function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>REFERENTIAL_CONSTRAINTS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>REGEXP_MATCHES function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>REGEXP_SUBSTRING_ARRAY function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>REGEXP_SUBSTRING function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>RELEASE SAVEPOINT, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>RENAME, <a class="indexterm" href="#dbc_renaming">Renaming Objects</a>
</dt>
<dt>REPEAT ... UNTIL loop in routines, <a class="indexterm" href="#src_psm_iterated_statements">Iterated Statements</a>
</dt>
<dt>REPEAT function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>REPLACE function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>RESIGNAL STATEMENT, <a class="indexterm" href="#src_psm_exceptions">Raising Exceptions</a>
</dt>
<dt>RETURN, <a class="indexterm" href="#src_psm_return_statement">Return Statement</a>
</dt>
<dt>RETURNS, <a class="indexterm" href="#src_routine_definition">Routine Definition</a>
</dt>
<dt>REVERSE function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>REVOKE, <a class="indexterm" href="#acc_statements">Statements for
    Authorization and Access Control</a>
</dt>
<dt>REVOKE ROLE, <a class="indexterm" href="#acc_statements">Statements for
    Authorization and Access Control</a>
</dt>
<dt>RIGHT function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>ROLE_AUTHORIZATION_DESCRIPTORS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>ROLE_COLUMN_GRANTS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>ROLE_ROUTINE_GRANTS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>ROLE_TABLE_GRANTS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>ROLE_UDT_GRANTS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>ROLE_USAGE_GRANTS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>ROLLBACK, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>ROLLBACK TO SAVEPOINT, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>ROUND function datetime, <a class="indexterm" href="#bfc_datetime_arithmetic">Functions for Datetime Arithmetic</a>
</dt>
<dt>ROUND number function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>ROUTINE_COLUMN_USAGE, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>ROUTINE_JAR_USAGE, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>ROUTINE_PRIVILEGES, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>ROUTINE_ROUTINE_USAGE, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>ROUTINE_SEQUENCE_USAGE, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>ROUTINE_TABLE_USAGE, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>routine body, <a class="indexterm" href="#src_routine_definition">Routine Definition</a>
</dt>
<dt>routine invocation, <a class="indexterm" href="#dac_other_syntax_elements">Other Syntax Elements</a>
</dt>
<dt>ROUTINES, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>ROW_NUMBER function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>ROWNUM function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>row value expression, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
<dt>RPAD function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>RTRIM function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>S</h3>
<dl>
<dt>SAVEPOINT, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>SAVEPOINT LEVEL, <a class="indexterm" href="#src_routine_characteristics">Routine Characteristics</a>
</dt>
<dt>schema routine, <a class="indexterm" href="#dbc_routine_creation">Routine Creation</a>
</dt>
<dt>SCHEMATA, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>SCRIPT, <a class="indexterm" href="#mtc_system_operations">System Operations</a>
</dt>
<dt>search condition, <a class="indexterm" href="#dac_other_syntax_elements">Other Syntax Elements</a>
</dt>
<dt>SECOND function, <a class="indexterm" href="#bfc_extract_datetime">Functions to Extract an Element of a Datetime</a>
</dt>
<dt>SECONDS_SINCE_MIDNIGHT function, <a class="indexterm" href="#bfc_extract_datetime">Functions to Extract an Element of a Datetime</a>
</dt>
<dt>SELECT, <a class="indexterm" href="#dac_sql_select_statement">Select Statement</a>
</dt>
<dt>SELECT : SINGLE ROW, <a class="indexterm" href="#src_psm_select_single">Select Statement : Single Row</a>
</dt>
<dt>SEQUENCE_ARRAY function, <a class="indexterm" href="#bfc_array_functions">Array Functions</a>
</dt>
<dt>SEQUENCES, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>SESSION_ID function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>SESSION_ISOLATION_LEVEL function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>SESSION_TIMEZONE function, <a class="indexterm" href="#bfc_timezone_functions">Functions to Report the Time Zone.</a>
</dt>
<dt>SESSION_USER function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>SESSIONTIMEZONE function, <a class="indexterm" href="#bfc_timezone_functions">Functions to Report the Time Zone.</a>
</dt>
<dt>SET AUTOCOMMIT, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>SET CATALOG, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>set clause in UPDATE and MERGE statements, <a class="indexterm" href="#dac_update_statement">Update Statement</a>
</dt>
<dt>SET CONSTRAINTS, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>SET DATABASE AUTHENTICATION FUNCTION, <a class="indexterm" href="#mtc_authntication_settings">Authentication Settings</a>
</dt>
<dt>SET DATABASE COLLATION, <a class="indexterm" href="#mtc_database_settings">Database Settings</a>
</dt>
<dt>SET DATABASE DEFAULT INITIAL SCHEMA, <a class="indexterm" href="#acc_statements">Statements for
    Authorization and Access Control</a>
</dt>
<dt>SET DATABASE DEFAULT ISOLATION LEVEL, <a class="indexterm" href="#mtc_database_settings">Database Settings</a>
</dt>
<dt>SET DATABASE DEFAULT RESULT MEMORY ROWS, <a class="indexterm" href="#mtc_database_settings">Database Settings</a>
</dt>
<dt>SET DATABASE DEFAULT TABLE TYPE, <a class="indexterm" href="#mtc_database_settings">Database Settings</a>
</dt>
<dt>SET DATABASE EVENT LOG LEVEL, <a class="indexterm" href="#mtc_database_settings">Database Settings</a>
</dt>
<dt>SET DATABASE GC, <a class="indexterm" href="#mtc_database_settings">Database Settings</a>
</dt>
<dt>SET DATABASE PASSWORD CHECK FUNCTION, <a class="indexterm" href="#mtc_authntication_settings">Authentication Settings</a>
</dt>
<dt>SET DATABASE SQL AVG SCALE, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE SQL CONCAT NULLS, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE SQL CONVERT TRUNCATE, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE SQL DOUBLE NAN, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE SQL IGNORECASE, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE SQL NAMES, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE SQL NULLS FIRST, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE SQL NULLS ORDER, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE SQL REFERENCES, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE SQL REGULAR NAMES, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE SQL SIZE, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE SQL SYNTAX DB2, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE SQL SYNTAX MSS, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE SQL SYNTAX MYS, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE SQL SYNTAX ORA, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE SQL SYNTAX PGS, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE SQL TDC DELETE, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE SQL TRANSLATE TTI TYPES, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE SQL TYPES, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE SQL UNIQUE NULLS, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE TEXT TABLE DEFAULTS, <a class="indexterm" href="#mtc_database_settings">Database Settings</a>
</dt>
<dt>SET DATABASE TRANSACTION CONTROL, <a class="indexterm" href="#mtc_database_settings">Database Settings</a>
</dt>
<dt>SET DATABASE TRANSACTION ROLLBACK ON CONFLICT, <a class="indexterm" href="#mtc_database_settings">Database Settings</a>
</dt>
<dt>SET DATABASE UNIQUE NAME, <a class="indexterm" href="#mtc_database_settings">Database Settings</a>
</dt>
<dt>SET DATA TYPE, <a class="indexterm" href="#dbc_table_manupulation">Table Manipulation</a>
</dt>
<dt>SET DEFAULT, <a class="indexterm" href="#dbc_table_manupulation">Table Manipulation</a>
</dt>
<dt>SET DOMAIN DEFAULT, <a class="indexterm" href="#dbc_domain_creation">Domain Creation and Manipulation</a>
</dt>
<dt>SET FILES BACKUP INCREMENT, <a class="indexterm" href="#mtc_cache_persistence">Cache, Persistence and Files Settings</a>
</dt>
<dt>SET FILES CACHE ROWS, <a class="indexterm" href="#mtc_cache_persistence">Cache, Persistence and Files Settings</a>
</dt>
<dt>SET FILES CACHE SIZE, <a class="indexterm" href="#mtc_cache_persistence">Cache, Persistence and Files Settings</a>
</dt>
<dt>SET FILES DEFRAG, <a class="indexterm" href="#mtc_cache_persistence">Cache, Persistence and Files Settings</a>
</dt>
<dt>SET FILES LOB COMPRESSED, <a class="indexterm" href="#mtc_cache_persistence">Cache, Persistence and Files Settings</a>
</dt>
<dt>SET FILES LOB SCALE, <a class="indexterm" href="#mtc_cache_persistence">Cache, Persistence and Files Settings</a>
</dt>
<dt>SET FILES LOG, <a class="indexterm" href="#mtc_cache_persistence">Cache, Persistence and Files Settings</a>
</dt>
<dt>SET FILES LOG SIZE, <a class="indexterm" href="#mtc_cache_persistence">Cache, Persistence and Files Settings</a>
</dt>
<dt>SET FILES NIO, <a class="indexterm" href="#mtc_cache_persistence">Cache, Persistence and Files Settings</a>
</dt>
<dt>SET FILES NIO SIZE, <a class="indexterm" href="#mtc_cache_persistence">Cache, Persistence and Files Settings</a>
</dt>
<dt>SET FILES SCALE, <a class="indexterm" href="#mtc_cache_persistence">Cache, Persistence and Files Settings</a>
</dt>
<dt>SET FILES SCRIPT FORMAT, <a class="indexterm" href="#mtc_cache_persistence">Cache, Persistence and Files Settings</a>
</dt>
<dt>SET FILES WRITE DELAY, <a class="indexterm" href="#mtc_cache_persistence">Cache, Persistence and Files Settings</a>
</dt>
<dt>set function specification, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
<dt>SET IGNORECASE, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>SET INITIAL SCHEMA*, <a class="indexterm" href="#acc_statements">Statements for
    Authorization and Access Control</a>
</dt>
<dt>SET MAXROWS, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>SET OPERATIONS, <a class="indexterm" href="#dac_set_operations">Set Operations</a>
</dt>
<dt>SET PASSWORD, <a class="indexterm" href="#acc_statements">Statements for
    Authorization and Access Control</a>
</dt>
<dt>SET PATH, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>SET REFERENTIAL INTEGRITY, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET ROLE, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>SET SCHEMA, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>SET SESSION AUTHORIZATION, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>SET SESSION CHARACTERISTICS, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>SET SESSION RESULT MEMORY ROWS, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>SET TABLE CLUSTERED, <a class="indexterm" href="#dbc_table_manupulation">Table Manipulation</a>
</dt>
<dt>SET TABLE read-write property, <a class="indexterm" href="#dbc_table_manupulation">Table Manipulation</a>
</dt>
<dt>SET TABLE SOURCE, <a class="indexterm" href="#dbc_table_manupulation">Table Manipulation</a>
</dt>
<dt>SET TABLE SOURCE HEADER, <a class="indexterm" href="#dbc_table_manupulation">Table Manipulation</a>
</dt>
<dt>SET TABLE SOURCE on-off, <a class="indexterm" href="#dbc_table_manupulation">Table Manipulation</a>
</dt>
<dt>SET TABLE TYPE, <a class="indexterm" href="#dbc_table_manupulation">Table Manipulation</a>, <a class="indexterm" href="#mtc_cache_persistence">Cache, Persistence and Files Settings</a>
</dt>
<dt>SET TIME ZONE, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>SET TRANSACTION, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>SHUTDOWN, <a class="indexterm" href="#mtc_system_operations">System Operations</a>
</dt>
<dt>SIGNAL STATEMENT, <a class="indexterm" href="#src_psm_exceptions">Raising Exceptions</a>
</dt>
<dt>SIGN function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>SIN function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>SORT_ARRAY function, <a class="indexterm" href="#bfc_array_functions">Array Functions</a>
</dt>
<dt>sort specification list, <a class="indexterm" href="#dac_ordering">Ordering</a>
</dt>
<dt>SOUNDEX function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>SPACE function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>SPECIFIC, <a class="indexterm" href="#dbc_common_elements">Common Elements and Statements</a>
</dt>
<dt>SPECIFIC NAME, <a class="indexterm" href="#src_routine_characteristics">Routine Characteristics</a>
</dt>
<dt>SQL_FEATURES, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>SQL_IMPLEMENTATION_INFO, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>SQL_PACKAGES, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>SQL_PARTS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>SQL_SIZING, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>SQL_SIZING_PROFILES, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>SQL DATA access characteristic, <a class="indexterm" href="#src_routine_characteristics">Routine Characteristics</a>
</dt>
<dt>SQL parameter reference, <a class="indexterm" href="#dac_sql_references">References, etc.</a>
</dt>
<dt>SQL procedure statement, <a class="indexterm" href="#dbc_procedure_satement">SQL Procedure Statement</a>
</dt>
<dt>SQL routine body, <a class="indexterm" href="#src_routine_definition">Routine Definition</a>
</dt>
<dt>SQRT function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>START TRANSACTION, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>string value expression, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
<dt>SUBSTR function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>SUBSTRING function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>SYSDATE function, <a class="indexterm" href="#bfc_current_datetime">Functions to Report the Current Datetime</a>
</dt>
<dt>SYSTEM_BESTROWIDENTIFIER, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_CACHEINFO, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_COLUMN_SEQUENCE_USAGE, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_COLUMNS, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_COMMENTS, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_CONNECTION_PROPERTIES, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_CROSSREFERENCE, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_INDEXINFO, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_PRIMARYKEYS, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_PROCEDURECOLUMNS, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_PROCEDURES, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_PROPERTIES, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_SCHEMAS, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_SEQUENCES, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_SESSIONINFO, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_SESSIONS, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_TABLES, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_TABLESTATS, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_TABLETYPES, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_TEXTTABLES, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_TYPEINFO, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_UDTS, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_USER function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>SYSTEM_USERS, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_VERSIONCOLUMNS, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTIMESTAMP function, <a class="indexterm" href="#bfc_current_datetime">Functions to Report the Current Datetime</a>
</dt>
<dt>SYS USER, <a class="indexterm" href="#acc_built_in_roles_users">Built-In Roles and Users</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>T</h3>
<dl>
<dt>TABLE_CONSTRAINTS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>TABLE_PRIVILEGES, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>Table Function Derived Table, <a class="indexterm" href="#dac_table_function">Table Function Derived Table</a>
</dt>
<dt>TABLES, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>TAN function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>TIMESTAMP_WITH_ZONE function, <a class="indexterm" href="#bfc_datetime_format">Functions to Convert or Format a Datetime</a>
</dt>
<dt>TIMESTAMPADD function, <a class="indexterm" href="#bfc_datetime_arithmetic">Functions for Datetime Arithmetic</a>
</dt>
<dt>TIMESTAMPDIFF function, <a class="indexterm" href="#bfc_datetime_arithmetic">Functions for Datetime Arithmetic</a>
</dt>
<dt>TIMESTAMP function, <a class="indexterm" href="#bfc_datetime_format">Functions to Convert or Format a Datetime</a>
</dt>
<dt>Time Zone, <a class="indexterm" href="#sgc_datetime_types">Datetime types</a>
</dt>
<dt>TIMEZONE function, <a class="indexterm" href="#bfc_timezone_functions">Functions to Report the Time Zone.</a>
</dt>
<dt>TO_CHAR function, <a class="indexterm" href="#bfc_datetime_format">Functions to Convert or Format a Datetime</a>
</dt>
<dt>TO_DATE function, <a class="indexterm" href="#bfc_datetime_format">Functions to Convert or Format a Datetime</a>
</dt>
<dt>TO_NUMBER function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>TO_TIMESTAMP function, <a class="indexterm" href="#bfc_datetime_format">Functions to Convert or Format a Datetime</a>
</dt>
<dt>TODAY function, <a class="indexterm" href="#bfc_current_datetime">Functions to Report the Current Datetime</a>
</dt>
<dt>TRANSACTION_CONTROL function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>TRANSACTION_ID function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>TRANSACTION_SIZE function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>transaction characteristics, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>TRANSLATE function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>TRANSLATIONS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>TRIGGER_COLUMN_USAGE, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>TRIGGER_ROUTINE_USAGE, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>TRIGGER_SEQUENCE_USAGE, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>TRIGGER_TABLE_USAGE, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>TRIGGERED_UPDATE_COLUMNS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>TRIGGERED SQL STATEMENT, <a class="indexterm" href="#trc_trigger_creation">Trigger Creation</a>
</dt>
<dt>TRIGGER EXECUTION ORDER, <a class="indexterm" href="#trc_trigger_creation">Trigger Creation</a>
</dt>
<dt>TRIGGERS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>TRIM_ARRAY function, <a class="indexterm" href="#bfc_array_functions">Array Functions</a>
</dt>
<dt>TRIM function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>TRUNCATE function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>TRUNCATE SCHEMA, <a class="indexterm" href="#dac_truncate_statement">Truncate Statement</a>
</dt>
<dt>TRUNCATE TABLE, <a class="indexterm" href="#dac_truncate_statement">Truncate Statement</a>
</dt>
<dt>TRUNC function datetime, <a class="indexterm" href="#bfc_datetime_arithmetic">Functions for Datetime Arithmetic</a>
</dt>
<dt>TRUNC function numeric, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>U</h3>
<dl>
<dt>UCASE function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>unicode escape elements, <a class="indexterm" href="#dac_literals">Literals</a>
</dt>
<dt>UNION JOIN, <a class="indexterm" href="#dac_joined_table">Joined Table</a>
</dt>
<dt>UNIQUE constraint, <a class="indexterm" href="#dbc_table_creation">Table Creation</a>
</dt>
<dt>UNIQUE predicate, <a class="indexterm" href="#dac_sql_predicates">Predicates</a>
</dt>
<dt>UNIX_TIMESTAMP function, <a class="indexterm" href="#bfc_extract_datetime">Functions to Extract an Element of a Datetime</a>
</dt>
<dt>UNNEST, <a class="indexterm" href="#dac_unnest">UNNEST</a>
</dt>
<dt>UPDATE, <a class="indexterm" href="#dac_update_statement">Update Statement</a>
</dt>
<dt>UPPER function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>USAGE_PRIVILEGES, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>USER_DEFINED_TYPES, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>USER function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>UUID function, <a class="indexterm" href="#bfc_general_functions">General Functions</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>V</h3>
<dl>
<dt>value expression, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
<dt>value expression primary, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
<dt>value specification, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
<dt>VIEW_COLUMN_USAGE, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>VIEW_ROUTINE_USAGE, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>VIEW_TABLE_USAGE, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>VIEWS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>W</h3>
<dl>
<dt>WEEK function, <a class="indexterm" href="#bfc_extract_datetime">Functions to Extract an Element of a Datetime</a>
</dt>
<dt>WHILE loop in routines, <a class="indexterm" href="#src_psm_iterated_statements">Iterated Statements</a>
</dt>
<dt>WIDTH_BUCKET function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>Y</h3>
<dl>
<dt>YEAR function, <a class="indexterm" href="#bfc_extract_datetime">Functions to Extract an Element of a Datetime</a>
</dt>
</dl>
</div>
</div>
</div>
<div class="index" title="General Index">
<div class="titlepage">
<div>
<div>
<h2 class="title">
<a name="book-ind"></a>General Index</h2>
</div>
</div>
</div>
<div class="index">
<div class="indexdiv">
<h3>Symbols</h3>
<dl>
<dt>_SYSTEM ROLE, <a class="indexterm" href="#acc_built_in_roles_users">Built-In Roles and Users</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>A</h3>
<dl>
<dt>ABS function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>ACL, <a class="indexterm" href="#lsc_acl">Network Access Control</a>
</dt>
<dt>ACOS function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>ACTION_ID function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>ADD_MONTHS function, <a class="indexterm" href="#bfc_datetime_arithmetic">Functions for Datetime Arithmetic</a>
</dt>
<dt>ADD COLUMN, <a class="indexterm" href="#dbc_table_manupulation">Table Manipulation</a>
</dt>
<dt>add column identity generator, <a class="indexterm" href="#dbc_table_manupulation">Table Manipulation</a>
</dt>
<dt>ADD CONSTRAINT, <a class="indexterm" href="#dbc_table_manupulation">Table Manipulation</a>
</dt>
<dt>ADD DOMAIN CONSTRAINT, <a class="indexterm" href="#dbc_domain_creation">Domain Creation and Manipulation</a>
</dt>
<dt>ADMINISTRABLE_ROLE_AUTHORIZATIONS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>aggregate function, <a class="indexterm" href="#dac_aggregate_funcs">Aggregate Functions</a>
</dt>
<dt>ALL and ANY predicates, <a class="indexterm" href="#dac_sql_predicates">Predicates</a>
</dt>
<dt>ALTER COLUMN, <a class="indexterm" href="#dbc_table_manupulation">Table Manipulation</a>
</dt>
<dt>alter column identity generator, <a class="indexterm" href="#dbc_table_manupulation">Table Manipulation</a>
</dt>
<dt>alter column nullability, <a class="indexterm" href="#dbc_table_manupulation">Table Manipulation</a>
</dt>
<dt>ALTER DOMAIN, <a class="indexterm" href="#dbc_domain_creation">Domain Creation and Manipulation</a>
</dt>
<dt>ALTER INDEX, <a class="indexterm" href="#dbc_other_object_creation">Other Schema Object Creation</a>
</dt>
<dt>ALTER routine, <a class="indexterm" href="#dbc_routine_creation">Routine Creation</a>
</dt>
<dt>ALTER SEQUENCE, <a class="indexterm" href="#dbc_sequence_creation">Sequence Creation</a>
</dt>
<dt>ALTER SESSION, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>ALTER TABLE, <a class="indexterm" href="#dbc_table_manupulation">Table Manipulation</a>
</dt>
<dt>ALTER USER ... SET INITIAL SCHEMA, <a class="indexterm" href="#acc_statements">Statements for
    Authorization and Access Control</a>
</dt>
<dt>ALTER USER ... SET LOCAL, <a class="indexterm" href="#acc_statements">Statements for
    Authorization and Access Control</a>
</dt>
<dt>ALTER USER ... SET PASSWORD, <a class="indexterm" href="#acc_statements">Statements for
    Authorization and Access Control</a>
</dt>
<dt>ALTER view, <a class="indexterm" href="#dbc_view_creation">View Creation and Manipulation</a>
</dt>
<dt>Ant, <a class="indexterm" href="#bga_building_ant">Building with Apache Ant</a>
</dt>
<dt>APPLICABLE_ROLES, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>ASCII function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>ASIN function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>ASSERTIONS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>ATAN2 function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>ATAN function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>AUTHORIZATION IDENTIFIER, <a class="indexterm" href="#acc_auth_and_access_ctrl">Authorizations and Access Control</a>
</dt>
<dt>AUTHORIZATIONS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>B</h3>
<dl>
<dt>backup, <a class="indexterm" href="#mtc_backup">Backing Up Database Catalogs</a>
</dt>
<dt>BACKUP DATABASE, <a class="indexterm" href="#mtc_system_operations">System Operations</a>
</dt>
<dt>BETWEEN predicate, <a class="indexterm" href="#dac_sql_predicates">Predicates</a>
</dt>
<dt>binary literal, <a class="indexterm" href="#dac_literals">Literals</a>
</dt>
<dt>BINARY types, <a class="indexterm" href="#sgc_binary_types">Binary String Types</a>
</dt>
<dt>BIT_LENGTH function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>BITAND function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>BITANDNOT function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>bit literal, <a class="indexterm" href="#dac_literals">Literals</a>
</dt>
<dt>BITNOT function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>BITOR function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>BIT types, <a class="indexterm" href="#sgc_bit_types">Bit String Types</a>
</dt>
<dt>BITXOR function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>boolean literal, <a class="indexterm" href="#dac_literals">Literals</a>
</dt>
<dt>BOOLEAN types, <a class="indexterm" href="#sgc_boolean_type">Boolean Type</a>
</dt>
<dt>boolean value expression, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>C</h3>
<dl>
<dt>CARDINALITY function, <a class="indexterm" href="#bfc_array_functions">Array Functions</a>
</dt>
<dt>CASCADE or RESTRICT, <a class="indexterm" href="#dbc_common_elements">Common Elements and Statements</a>
</dt>
<dt>case expression, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
<dt>CASEWHEN function, <a class="indexterm" href="#bfc_general_functions">General Functions</a>
</dt>
<dt>CASE WHEN in routines, <a class="indexterm" href="#src_psm_conditional">Conditional Statements</a>
</dt>
<dt>CAST, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
<dt>CEIL function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>CHANGE_AUTHORIZATION, <a class="indexterm" href="#acc_built_in_roles_users">Built-In Roles and Users</a>
</dt>
<dt>CHAR_LENGTH, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>CHARACTER_LENGTH, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>CHARACTER_SETS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>character literal, <a class="indexterm" href="#dac_literals">Literals</a>
</dt>
<dt>CHARACTER types, <a class="indexterm" href="#sgc_char_types">Character String Types</a>
</dt>
<dt>character value function, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
<dt>CHAR function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>CHECK_CONSTRAINT_ROUTINE_USAGE, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>CHECK_CONSTRAINTS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>CHECK constraint, <a class="indexterm" href="#dbc_table_creation">Table Creation</a>
</dt>
<dt>CHECKPOINT, <a class="indexterm" href="#mtc_system_operations">System Operations</a>
</dt>
<dt>COALESCE expression, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
<dt>COALESCE function, <a class="indexterm" href="#bfc_general_functions">General Functions</a>
</dt>
<dt>COLLATE, <a class="indexterm" href="#dac_other_syntax_elements">Other Syntax Elements</a>
</dt>
<dt>COLLATIONS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>COLUMN_COLUMN_USAGE, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>COLUMN_DOMAIN_USAGE, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>COLUMN_PRIVILEGES, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>COLUMN_UDT_USAGE, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>column definition, <a class="indexterm" href="#dbc_table_creation">Table Creation</a>
</dt>
<dt>column name list, <a class="indexterm" href="#dac_col_name_list">Column Name List</a>
</dt>
<dt>column reference, <a class="indexterm" href="#dac_sql_references">References, etc.</a>
</dt>
<dt>COLUMNS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>COMMENT, <a class="indexterm" href="#dbc_commenting">Commenting Objects</a>
</dt>
<dt>COMMIT, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>comparison predicate, <a class="indexterm" href="#dac_sql_predicates">Predicates</a>
</dt>
<dt>CONCAT_WS function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>CONCAT function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>CONSTRAINT, <a class="indexterm" href="#dac_other_syntax_elements">Other Syntax Elements</a>
</dt>
<dt>CONSTRAINT_COLUMN_USAGE, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>CONSTRAINT_TABLE_USAGE, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>CONSTRAINT (table constraint), <a class="indexterm" href="#dbc_table_creation">Table Creation</a>
</dt>
<dt>CONSTRAINT name and characteristics, <a class="indexterm" href="#dbc_table_creation">Table Creation</a>
</dt>
<dt>contextually typed value specification, <a class="indexterm" href="#dac_sql_references">References, etc.</a>
</dt>
<dt>CONVERT function, <a class="indexterm" href="#bfc_general_functions">General Functions</a>
</dt>
<dt>COS function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>COT function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>CREATE_SCHEMA ROLE, <a class="indexterm" href="#acc_built_in_roles_users">Built-In Roles and Users</a>
</dt>
<dt>CREATE AGGREGATE FUNCTION, <a class="indexterm" href="#src_aggregate_function_definition">Definition of Aggregate Functions</a>
</dt>
<dt>CREATE ASSERTION, <a class="indexterm" href="#dbc_other_object_creation">Other Schema Object Creation</a>
</dt>
<dt>CREATE CAST, <a class="indexterm" href="#dbc_other_object_creation">Other Schema Object Creation</a>
</dt>
<dt>CREATE CHARACTER SET, <a class="indexterm" href="#dbc_other_object_creation">Other Schema Object Creation</a>
</dt>
<dt>CREATE COLLATION, <a class="indexterm" href="#dbc_other_object_creation">Other Schema Object Creation</a>
</dt>
<dt>CREATE DOMAIN, <a class="indexterm" href="#dbc_domain_creation">Domain Creation and Manipulation</a>
</dt>
<dt>CREATE FUNCTION, <a class="indexterm" href="#src_routine_definition">Routine Definition</a>
</dt>
<dt>CREATE INDEX, <a class="indexterm" href="#dbc_other_object_creation">Other Schema Object Creation</a>
</dt>
<dt>CREATE PROCEDURE, <a class="indexterm" href="#src_routine_definition">Routine Definition</a>
</dt>
<dt>CREATE ROLE, <a class="indexterm" href="#acc_statements">Statements for
    Authorization and Access Control</a>
</dt>
<dt>CREATE SCHEMA, <a class="indexterm" href="#dbc_schema_creation">Schema Creation</a>
</dt>
<dt>CREATE SEQUENCE, <a class="indexterm" href="#dbc_sequence_creation">Sequence Creation</a>
</dt>
<dt>CREATE TABLE, <a class="indexterm" href="#dbc_table_creation">Table Creation</a>
</dt>
<dt>CREATE TRANSLATION, <a class="indexterm" href="#dbc_other_object_creation">Other Schema Object Creation</a>
</dt>
<dt>CREATE TRIGGER, <a class="indexterm" href="#dbc_trigger_creation">Trigger Creation</a>, <a class="indexterm" href="#trc_trigger_creation">Trigger Creation</a>
</dt>
<dt>CREATE TYPE, <a class="indexterm" href="#dbc_other_object_creation">Other Schema Object Creation</a>
</dt>
<dt>CREATE USER, <a class="indexterm" href="#acc_statements">Statements for
    Authorization and Access Control</a>
</dt>
<dt>CREATE VIEW, <a class="indexterm" href="#dbc_view_creation">View Creation and Manipulation</a>
</dt>
<dt>CROSS JOIN, <a class="indexterm" href="#dac_joined_table">Joined Table</a>
</dt>
<dt>CRYPT_KEY function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>CURDATE function, <a class="indexterm" href="#bfc_current_datetime">Functions to Report the Current Datetime</a>
</dt>
<dt>CURRENT_CATALOG function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>CURRENT_DATE function, <a class="indexterm" href="#bfc_current_datetime">Functions to Report the Current Datetime</a>
</dt>
<dt>CURRENT_ROLE function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>CURRENT_SCHEMA function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>CURRENT_TIME function, <a class="indexterm" href="#bfc_current_datetime">Functions to Report the Current Datetime</a>
</dt>
<dt>CURRENT_TIMESTAMP function, <a class="indexterm" href="#bfc_current_datetime">Functions to Report the Current Datetime</a>
</dt>
<dt>CURRENT_USER function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>CURRENT VALUE FOR, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
<dt>CURTIME function, <a class="indexterm" href="#bfc_current_datetime">Functions to Report the Current Datetime</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>D</h3>
<dl>
<dt>DATA_TYPE_PRIVILEGES, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>DATABASE_ISOLATION_LEVEL function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>DATABASE_NAME function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>DATABASE_TIMEZONE function, <a class="indexterm" href="#bfc_timezone_functions">Functions to Report the Time Zone.</a>
</dt>
<dt>DATABASE_VERSION function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>DATABASE function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>DATE_ADD function, <a class="indexterm" href="#bfc_datetime_arithmetic">Functions for Datetime Arithmetic</a>
</dt>
<dt>DATE_SUB function, <a class="indexterm" href="#bfc_datetime_arithmetic">Functions for Datetime Arithmetic</a>
</dt>
<dt>DATEADD function, <a class="indexterm" href="#bfc_datetime_arithmetic">Functions for Datetime Arithmetic</a>
</dt>
<dt>DATEDIFF function, <a class="indexterm" href="#bfc_datetime_arithmetic">Functions for Datetime Arithmetic</a>
</dt>
<dt>datetime and interval literal, <a class="indexterm" href="#dac_literals">Literals</a>
</dt>
<dt>Datetime Operations, <a class="indexterm" href="#sgc_datetime_types">Datetime types</a>
</dt>
<dt>DATETIME types, <a class="indexterm" href="#sgc_datetime_types">Datetime types</a>
</dt>
<dt>datetime value expression, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
<dt>datetime value function, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
<dt>DAYNAME function, <a class="indexterm" href="#bfc_extract_datetime">Functions to Extract an Element of a Datetime</a>
</dt>
<dt>DAYOFMONTH function, <a class="indexterm" href="#bfc_extract_datetime">Functions to Extract an Element of a Datetime</a>
</dt>
<dt>DAYOFWEEK function, <a class="indexterm" href="#bfc_extract_datetime">Functions to Extract an Element of a Datetime</a>
</dt>
<dt>DAYOFYEAR function, <a class="indexterm" href="#bfc_extract_datetime">Functions to Extract an Element of a Datetime</a>
</dt>
<dt>DAYS function datetime, <a class="indexterm" href="#bfc_extract_datetime">Functions to Extract an Element of a Datetime</a>
</dt>
<dt>DBA ROLE, <a class="indexterm" href="#acc_built_in_roles_users">Built-In Roles and Users</a>
</dt>
<dt>DECLARE CURSOR, <a class="indexterm" href="#dac_declare_cursor">Cursor Declaration</a>
</dt>
<dt>DECLARE HANDLER, <a class="indexterm" href="#src_psm_handlers">Handlers</a>
</dt>
<dt>DECLARE variable, <a class="indexterm" href="#src_psm_vars">Variables</a>
</dt>
<dt>DECODE function, <a class="indexterm" href="#bfc_general_functions">General Functions</a>
</dt>
<dt>DEFAULT clause, <a class="indexterm" href="#dbc_table_creation">Table Creation</a>
</dt>
<dt>DEGREES function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>DELETE FROM, <a class="indexterm" href="#dac_delete_statement">Delete Statement</a>
</dt>
<dt>derived table, <a class="indexterm" href="#dac_derived_table">Derived Table</a>
</dt>
<dt>DETERMINISTIC characteristic, <a class="indexterm" href="#src_routine_characteristics">Routine Characteristics</a>
</dt>
<dt>DIAGNOSTICS function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>DIFFERENCE function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>DISCONNECT, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>DISTINCT, <a class="indexterm" href="#dac_grouping_operations">Grouping Operations</a>
</dt>
<dt>DOMAIN_CONSTRAINTS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>DOMAINS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>DROP ASSERTION, <a class="indexterm" href="#dbc_other_object_creation">Other Schema Object Creation</a>
</dt>
<dt>DROP CAST, <a class="indexterm" href="#dbc_other_object_creation">Other Schema Object Creation</a>
</dt>
<dt>DROP CHARACTER SET, <a class="indexterm" href="#dbc_other_object_creation">Other Schema Object Creation</a>
</dt>
<dt>DROP COLLATION, <a class="indexterm" href="#dbc_other_object_creation">Other Schema Object Creation</a>
</dt>
<dt>DROP COLUMN, <a class="indexterm" href="#dbc_table_manupulation">Table Manipulation</a>
</dt>
<dt>drop column idenitty generator, <a class="indexterm" href="#dbc_table_manupulation">Table Manipulation</a>
</dt>
<dt>DROP CONSTRAINT, <a class="indexterm" href="#dbc_table_manupulation">Table Manipulation</a>
</dt>
<dt>DROP DEFAULT (table), <a class="indexterm" href="#dbc_table_manupulation">Table Manipulation</a>
</dt>
<dt>DROP DOMAIN, <a class="indexterm" href="#dbc_domain_creation">Domain Creation and Manipulation</a>
</dt>
<dt>DROP DOMAIN CONSTRAINT, <a class="indexterm" href="#dbc_domain_creation">Domain Creation and Manipulation</a>
</dt>
<dt>DROP DOMAIN DEFAULT, <a class="indexterm" href="#dbc_domain_creation">Domain Creation and Manipulation</a>
</dt>
<dt>DROP INDEX, <a class="indexterm" href="#dbc_other_object_creation">Other Schema Object Creation</a>
</dt>
<dt>DROP ROLE, <a class="indexterm" href="#acc_statements">Statements for
    Authorization and Access Control</a>
</dt>
<dt>DROP routine, <a class="indexterm" href="#dbc_routine_creation">Routine Creation</a>
</dt>
<dt>DROP SCHEMA, <a class="indexterm" href="#dbc_schema_creation">Schema Creation</a>
</dt>
<dt>DROP SEQUENCE, <a class="indexterm" href="#dbc_sequence_creation">Sequence Creation</a>
</dt>
<dt>DROP TABLE, <a class="indexterm" href="#dbc_table_creation">Table Creation</a>
</dt>
<dt>DROP TRANSLATION, <a class="indexterm" href="#dbc_other_object_creation">Other Schema Object Creation</a>
</dt>
<dt>DROP TRIGGER, <a class="indexterm" href="#dbc_trigger_creation">Trigger Creation</a>, <a class="indexterm" href="#trc_trigger_creation">Trigger Creation</a>
</dt>
<dt>DROP USER, <a class="indexterm" href="#acc_statements">Statements for
    Authorization and Access Control</a>
</dt>
<dt>DROP VIEW, <a class="indexterm" href="#dbc_view_creation">View Creation and Manipulation</a>
</dt>
<dt>DYNAMIC RESULT SETS, <a class="indexterm" href="#src_routine_characteristics">Routine Characteristics</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>E</h3>
<dl>
<dt>ELEMENT_TYPES, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>ENABLED_ROLES, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>EXISTS predicate, <a class="indexterm" href="#dac_sql_predicates">Predicates</a>
</dt>
<dt>EXP function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>expression, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
<dt>external authentication, <a class="indexterm" href="#mtc_authentication_control">Authentication Control</a>
</dt>
<dt>EXTERNAL NAME, <a class="indexterm" href="#src_routine_definition">Routine Definition</a>
</dt>
<dt>EXTRACT function, <a class="indexterm" href="#bfc_extract_datetime">Functions to Extract an Element of a Datetime</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>F</h3>
<dl>
<dt>FLOOR function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>FOREIGN KEY constraint, <a class="indexterm" href="#dbc_table_creation">Table Creation</a>
</dt>
<dt>FOR loop in routines, <a class="indexterm" href="#src_psm_for_statement">Iterated FOR Statement</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>G</h3>
<dl>
<dt>generated column specification, <a class="indexterm" href="#dbc_table_creation">Table Creation</a>
</dt>
<dt>GET DIAGNOSTICS, <a class="indexterm" href="#dac_diagnostics_state">Diagnostics and State</a>
</dt>
<dt>Gradle, <a class="indexterm" href="#bga_gradle_invoke">Building with Gradle</a>
</dt>
<dt>GRANTED BY, <a class="indexterm" href="#acc_statements">Statements for
    Authorization and Access Control</a>
</dt>
<dt>GRANT privilege, <a class="indexterm" href="#acc_statements">Statements for
    Authorization and Access Control</a>
</dt>
<dt>GRANT role, <a class="indexterm" href="#acc_statements">Statements for
    Authorization and Access Control</a>
</dt>
<dt>GREATEST function, <a class="indexterm" href="#bfc_general_functions">General Functions</a>
</dt>
<dt>GROUP BY, <a class="indexterm" href="#dac_grouping_operations">Grouping Operations</a>
</dt>
<dt>GROUPING OPERATIONS, <a class="indexterm" href="#dac_grouping_operations">Grouping Operations</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>H</h3>
<dl>
<dt>HEXTORAW function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>HOUR function, <a class="indexterm" href="#bfc_extract_datetime">Functions to Extract an Element of a Datetime</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>I</h3>
<dl>
<dt>identifier chain, <a class="indexterm" href="#dac_sql_references">References, etc.</a>
</dt>
<dt>identifier definition, <a class="indexterm" href="#dbc_common_elements">Common Elements and Statements</a>
</dt>
<dt>IDENTITY function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>IF EXISTS, <a class="indexterm" href="#dbc_common_elements">Common Elements and Statements</a>
</dt>
<dt>IFNULL function, <a class="indexterm" href="#bfc_general_functions">General Functions</a>
</dt>
<dt>IF STATEMENT, <a class="indexterm" href="#src_psm_conditional">Conditional Statements</a>
</dt>
<dt>INFORMATION_SCHEMA_CATALOG_NAME, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>init script, <a class="indexterm" href="#uxc_daemon">Running Hsqldb as a System Daemon</a>
</dt>
<dt>IN predicate, <a class="indexterm" href="#dac_sql_predicates">Predicates</a>
</dt>
<dt>INSERT function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>INSERT INTO, <a class="indexterm" href="#dac_insert_statement">Insert Statement</a>
</dt>
<dt>INSTR function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>interval absolute value function, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
<dt>interval term, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
<dt>INTERVAL types, <a class="indexterm" href="#sgc_interval_typs">Interval Types</a>
</dt>
<dt>IS_AUTOCOMMIT function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>IS_READONLY_DATABASE_FILES function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>IS_READONLY_DATABASE function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>IS_READONLY_SESSION function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>IS DISTINCT predicate, <a class="indexterm" href="#dac_sql_predicates">Predicates</a>
</dt>
<dt>ISNULL function, <a class="indexterm" href="#bfc_general_functions">General Functions</a>
</dt>
<dt>IS NULL predicate, <a class="indexterm" href="#dac_sql_predicates">Predicates</a>
</dt>
<dt>ISOLATION_LEVEL function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>J</h3>
<dl>
<dt>JOIN USING, <a class="indexterm" href="#dac_joined_table">Joined Table</a>
</dt>
<dt>JOIN with condition, <a class="indexterm" href="#dac_joined_table">Joined Table</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>K</h3>
<dl>
<dt>KEY_COLUMN_USAGE, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>L</h3>
<dl>
<dt>LANGUAGE, <a class="indexterm" href="#src_routine_characteristics">Routine Characteristics</a>
</dt>
<dt>LAST_DAY function, <a class="indexterm" href="#bfc_datetime_arithmetic">Functions for Datetime Arithmetic</a>
</dt>
<dt>LATERAL, <a class="indexterm" href="#dac_lateral">Lateral</a>
</dt>
<dt>LCASE function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>LEAST function, <a class="indexterm" href="#bfc_general_functions">General Functions</a>
</dt>
<dt>LEFT function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>LENGTH function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>LIKE predicate, <a class="indexterm" href="#dac_sql_predicates">Predicates</a>
</dt>
<dt>LN function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>LOAD_FILE function, <a class="indexterm" href="#bfc_general_functions">General Functions</a>
</dt>
<dt>LOB_ID function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>LOCALTIME function, <a class="indexterm" href="#bfc_current_datetime">Functions to Report the Current Datetime</a>
</dt>
<dt>LOCALTIMESTAMP function, <a class="indexterm" href="#bfc_current_datetime">Functions to Report the Current Datetime</a>
</dt>
<dt>LOCATE function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>LOCK TABLE, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>LOG10 function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>LOG function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>LOOP in routines, <a class="indexterm" href="#src_psm_iterated_statements">Iterated Statements</a>
</dt>
<dt>LPAD function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>LTRIM function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>M</h3>
<dl>
<dt>MATCH predicate, <a class="indexterm" href="#dac_sql_predicates">Predicates</a>
</dt>
<dt>MAX_CARDINALITY function, <a class="indexterm" href="#bfc_array_functions">Array Functions</a>
</dt>
<dt>memory use, <a class="indexterm" href="#dec_mem_disk_use">Memory and Disk Use</a>
</dt>
<dt>MERGE INTO, <a class="indexterm" href="#dac_merge_statement">Merge Statement</a>
</dt>
<dt>MINUTE function, <a class="indexterm" href="#bfc_extract_datetime">Functions to Extract an Element of a Datetime</a>
</dt>
<dt>MOD function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>MONTH function, <a class="indexterm" href="#bfc_extract_datetime">Functions to Extract an Element of a Datetime</a>
</dt>
<dt>MONTHNAME function, <a class="indexterm" href="#bfc_extract_datetime">Functions to Extract an Element of a Datetime</a>
</dt>
<dt>MONTHS_BETWEEN function, <a class="indexterm" href="#bfc_datetime_arithmetic">Functions for Datetime Arithmetic</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>N</h3>
<dl>
<dt>name resolution, <a class="indexterm" href="#dac_naming">Naming</a>
</dt>
<dt>naming in joined table, <a class="indexterm" href="#dac_naming">Naming</a>
</dt>
<dt>naming in select list, <a class="indexterm" href="#dac_naming">Naming</a>
</dt>
<dt>NATURAL JOIN, <a class="indexterm" href="#dac_joined_table">Joined Table</a>
</dt>
<dt>NEXT VALUE FOR, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
<dt>NOW function, <a class="indexterm" href="#bfc_current_datetime">Functions to Report the Current Datetime</a>
</dt>
<dt>NULLIF function, <a class="indexterm" href="#bfc_general_functions">General Functions</a>
</dt>
<dt>NULL INPUT, <a class="indexterm" href="#src_routine_characteristics">Routine Characteristics</a>
</dt>
<dt>numeric literal, <a class="indexterm" href="#dac_literals">Literals</a>
</dt>
<dt>NUMERIC types, <a class="indexterm" href="#sgc_numeric_types">Numeric Types</a>
</dt>
<dt>numeric value expression, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
<dt>numeric value function, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
<dt>NVL2 function, <a class="indexterm" href="#bfc_general_functions">General Functions</a>
</dt>
<dt>NVL function, <a class="indexterm" href="#bfc_general_functions">General Functions</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>O</h3>
<dl>
<dt>OCTET_LENGTH function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>OTHER type, <a class="indexterm" href="#sgc_java_objects">Storage and Handling of Java Objects</a>
</dt>
<dt>OUTER JOIN, <a class="indexterm" href="#dac_joined_table">Joined Table</a>
</dt>
<dt>OVERLAPS predicate, <a class="indexterm" href="#dac_sql_predicates">Predicates</a>
</dt>
<dt>OVERLAY function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>P</h3>
<dl>
<dt>PARAMETERS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>password complexity, <a class="indexterm" href="#mtc_authentication_control">Authentication Control</a>
</dt>
<dt>PATH, <a class="indexterm" href="#dac_other_syntax_elements">Other Syntax Elements</a>
</dt>
<dt>PI function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>POSITION_ARRAY function, <a class="indexterm" href="#bfc_array_functions">Array Functions</a>
</dt>
<dt>POSITION function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>POWER function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>PRIMARY KEY constraint, <a class="indexterm" href="#dbc_table_creation">Table Creation</a>
</dt>
<dt>PUBLIC ROLE, <a class="indexterm" href="#acc_built_in_roles_users">Built-In Roles and Users</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>Q</h3>
<dl>
<dt>QUARTER function, <a class="indexterm" href="#bfc_extract_datetime">Functions to Extract an Element of a Datetime</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>R</h3>
<dl>
<dt>RADIANS function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>RAND function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>RAWTOHEX function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>REFERENTIAL_CONSTRAINTS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>REGEXP_MATCHES function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>REGEXP_SUBSTRING_ARRAY function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>REGEXP_SUBSTRING function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>RELEASE SAVEPOINT, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>RENAME, <a class="indexterm" href="#dbc_renaming">Renaming Objects</a>
</dt>
<dt>REPEAT ... UNTIL loop in routines, <a class="indexterm" href="#src_psm_iterated_statements">Iterated Statements</a>
</dt>
<dt>REPEAT function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>REPLACE function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>RESIGNAL STATEMENT, <a class="indexterm" href="#src_psm_exceptions">Raising Exceptions</a>
</dt>
<dt>RETURN, <a class="indexterm" href="#src_psm_return_statement">Return Statement</a>
</dt>
<dt>RETURNS, <a class="indexterm" href="#src_routine_definition">Routine Definition</a>
</dt>
<dt>REVERSE function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>REVOKE, <a class="indexterm" href="#acc_statements">Statements for
    Authorization and Access Control</a>
</dt>
<dt>REVOKE ROLE, <a class="indexterm" href="#acc_statements">Statements for
    Authorization and Access Control</a>
</dt>
<dt>RIGHT function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>ROLE_AUTHORIZATION_DESCRIPTORS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>ROLE_COLUMN_GRANTS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>ROLE_ROUTINE_GRANTS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>ROLE_TABLE_GRANTS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>ROLE_UDT_GRANTS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>ROLE_USAGE_GRANTS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>ROLLBACK, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>ROLLBACK TO SAVEPOINT, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>ROUND function datetime, <a class="indexterm" href="#bfc_datetime_arithmetic">Functions for Datetime Arithmetic</a>
</dt>
<dt>ROUND number function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>ROUTINE_COLUMN_USAGE, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>ROUTINE_JAR_USAGE, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>ROUTINE_PRIVILEGES, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>ROUTINE_ROUTINE_USAGE, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>ROUTINE_SEQUENCE_USAGE, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>ROUTINE_TABLE_USAGE, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>routine body, <a class="indexterm" href="#src_routine_definition">Routine Definition</a>
</dt>
<dt>routine invocation, <a class="indexterm" href="#dac_other_syntax_elements">Other Syntax Elements</a>
</dt>
<dt>ROUTINES, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>ROW_NUMBER function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>ROWNUM function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>row value expression, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
<dt>RPAD function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>RTRIM function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>S</h3>
<dl>
<dt>SAVEPOINT, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>SAVEPOINT LEVEL, <a class="indexterm" href="#src_routine_characteristics">Routine Characteristics</a>
</dt>
<dt>schema routine, <a class="indexterm" href="#dbc_routine_creation">Routine Creation</a>
</dt>
<dt>SCHEMATA, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>SCRIPT, <a class="indexterm" href="#mtc_system_operations">System Operations</a>
</dt>
<dt>search condition, <a class="indexterm" href="#dac_other_syntax_elements">Other Syntax Elements</a>
</dt>
<dt>SECOND function, <a class="indexterm" href="#bfc_extract_datetime">Functions to Extract an Element of a Datetime</a>
</dt>
<dt>SECONDS_SINCE_MIDNIGHT function, <a class="indexterm" href="#bfc_extract_datetime">Functions to Extract an Element of a Datetime</a>
</dt>
<dt>security, <a class="indexterm" href="#rgc_security">Security Considerations</a>, <a class="indexterm" href="#lsc_tls">TLS Encryption</a>, <a class="indexterm" href="#lsc_acl">Network Access Control</a>
</dt>
<dt>SELECT, <a class="indexterm" href="#dac_sql_select_statement">Select Statement</a>
</dt>
<dt>SELECT : SINGLE ROW, <a class="indexterm" href="#src_psm_select_single">Select Statement : Single Row</a>
</dt>
<dt>SEQUENCE_ARRAY function, <a class="indexterm" href="#bfc_array_functions">Array Functions</a>
</dt>
<dt>SEQUENCES, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>SESSION_ID function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>SESSION_ISOLATION_LEVEL function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>SESSION_TIMEZONE function, <a class="indexterm" href="#bfc_timezone_functions">Functions to Report the Time Zone.</a>
</dt>
<dt>SESSION_USER function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>SESSIONTIMEZONE function, <a class="indexterm" href="#bfc_timezone_functions">Functions to Report the Time Zone.</a>
</dt>
<dt>SET AUTOCOMMIT, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>SET CATALOG, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>set clause in UPDATE and MERGE statements, <a class="indexterm" href="#dac_update_statement">Update Statement</a>
</dt>
<dt>SET CONSTRAINTS, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>SET DATABASE AUTHENTICATION FUNCTION, <a class="indexterm" href="#mtc_authntication_settings">Authentication Settings</a>
</dt>
<dt>SET DATABASE COLLATION, <a class="indexterm" href="#mtc_database_settings">Database Settings</a>
</dt>
<dt>SET DATABASE DEFAULT INITIAL SCHEMA, <a class="indexterm" href="#acc_statements">Statements for
    Authorization and Access Control</a>
</dt>
<dt>SET DATABASE DEFAULT ISOLATION LEVEL, <a class="indexterm" href="#mtc_database_settings">Database Settings</a>
</dt>
<dt>SET DATABASE DEFAULT RESULT MEMORY ROWS, <a class="indexterm" href="#mtc_database_settings">Database Settings</a>
</dt>
<dt>SET DATABASE DEFAULT TABLE TYPE, <a class="indexterm" href="#mtc_database_settings">Database Settings</a>
</dt>
<dt>SET DATABASE EVENT LOG LEVEL, <a class="indexterm" href="#mtc_database_settings">Database Settings</a>
</dt>
<dt>SET DATABASE GC, <a class="indexterm" href="#mtc_database_settings">Database Settings</a>
</dt>
<dt>SET DATABASE PASSWORD CHECK FUNCTION, <a class="indexterm" href="#mtc_authntication_settings">Authentication Settings</a>
</dt>
<dt>SET DATABASE SQL AVG SCALE, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE SQL CONCAT NULLS, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE SQL CONVERT TRUNCATE, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE SQL DOUBLE NAN, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE SQL IGNORECASE, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE SQL NAMES, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE SQL NULLS FIRST, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE SQL NULLS ORDER, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE SQL REFERENCES, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE SQL REGULAR NAMES, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE SQL SIZE, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE SQL SYNTAX DB2, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE SQL SYNTAX MSS, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE SQL SYNTAX MYS, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE SQL SYNTAX ORA, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE SQL SYNTAX PGS, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE SQL TDC DELETE, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE SQL TRANSLATE TTI TYPES, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE SQL TYPES, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE SQL UNIQUE NULLS, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET DATABASE TEXT TABLE DEFAULTS, <a class="indexterm" href="#mtc_database_settings">Database Settings</a>
</dt>
<dt>SET DATABASE TRANSACTION CONTROL, <a class="indexterm" href="#mtc_database_settings">Database Settings</a>
</dt>
<dt>SET DATABASE TRANSACTION ROLLBACK ON CONFLICT, <a class="indexterm" href="#mtc_database_settings">Database Settings</a>
</dt>
<dt>SET DATABASE UNIQUE NAME, <a class="indexterm" href="#mtc_database_settings">Database Settings</a>
</dt>
<dt>SET DATA TYPE, <a class="indexterm" href="#dbc_table_manupulation">Table Manipulation</a>
</dt>
<dt>SET DEFAULT, <a class="indexterm" href="#dbc_table_manupulation">Table Manipulation</a>
</dt>
<dt>SET DOMAIN DEFAULT, <a class="indexterm" href="#dbc_domain_creation">Domain Creation and Manipulation</a>
</dt>
<dt>SET FILES BACKUP INCREMENT, <a class="indexterm" href="#mtc_cache_persistence">Cache, Persistence and Files Settings</a>
</dt>
<dt>SET FILES CACHE ROWS, <a class="indexterm" href="#mtc_cache_persistence">Cache, Persistence and Files Settings</a>
</dt>
<dt>SET FILES CACHE SIZE, <a class="indexterm" href="#mtc_cache_persistence">Cache, Persistence and Files Settings</a>
</dt>
<dt>SET FILES DEFRAG, <a class="indexterm" href="#mtc_cache_persistence">Cache, Persistence and Files Settings</a>
</dt>
<dt>SET FILES LOB COMPRESSED, <a class="indexterm" href="#mtc_cache_persistence">Cache, Persistence and Files Settings</a>
</dt>
<dt>SET FILES LOB SCALE, <a class="indexterm" href="#mtc_cache_persistence">Cache, Persistence and Files Settings</a>
</dt>
<dt>SET FILES LOG, <a class="indexterm" href="#mtc_cache_persistence">Cache, Persistence and Files Settings</a>
</dt>
<dt>SET FILES LOG SIZE, <a class="indexterm" href="#mtc_cache_persistence">Cache, Persistence and Files Settings</a>
</dt>
<dt>SET FILES NIO, <a class="indexterm" href="#mtc_cache_persistence">Cache, Persistence and Files Settings</a>
</dt>
<dt>SET FILES NIO SIZE, <a class="indexterm" href="#mtc_cache_persistence">Cache, Persistence and Files Settings</a>
</dt>
<dt>SET FILES SCALE, <a class="indexterm" href="#mtc_cache_persistence">Cache, Persistence and Files Settings</a>
</dt>
<dt>SET FILES SCRIPT FORMAT, <a class="indexterm" href="#mtc_cache_persistence">Cache, Persistence and Files Settings</a>
</dt>
<dt>SET FILES WRITE DELAY, <a class="indexterm" href="#mtc_cache_persistence">Cache, Persistence and Files Settings</a>
</dt>
<dt>set function specification, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
<dt>SET IGNORECASE, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>SET INITIAL SCHEMA*, <a class="indexterm" href="#acc_statements">Statements for
    Authorization and Access Control</a>
</dt>
<dt>SET MAXROWS, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>SET OPERATIONS, <a class="indexterm" href="#dac_set_operations">Set Operations</a>
</dt>
<dt>SET PASSWORD, <a class="indexterm" href="#acc_statements">Statements for
    Authorization and Access Control</a>
</dt>
<dt>SET PATH, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>SET REFERENTIAL INTEGRITY, <a class="indexterm" href="#mtc_sql_settings">SQL Conformance Settings</a>
</dt>
<dt>SET ROLE, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>SET SCHEMA, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>SET SESSION AUTHORIZATION, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>SET SESSION CHARACTERISTICS, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>SET SESSION RESULT MEMORY ROWS, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>SET TABLE CLUSTERED, <a class="indexterm" href="#dbc_table_manupulation">Table Manipulation</a>
</dt>
<dt>SET TABLE read-write property, <a class="indexterm" href="#dbc_table_manupulation">Table Manipulation</a>
</dt>
<dt>SET TABLE SOURCE, <a class="indexterm" href="#dbc_table_manupulation">Table Manipulation</a>
</dt>
<dt>SET TABLE SOURCE HEADER, <a class="indexterm" href="#dbc_table_manupulation">Table Manipulation</a>
</dt>
<dt>SET TABLE SOURCE on-off, <a class="indexterm" href="#dbc_table_manupulation">Table Manipulation</a>
</dt>
<dt>SET TABLE TYPE, <a class="indexterm" href="#dbc_table_manupulation">Table Manipulation</a>, <a class="indexterm" href="#mtc_cache_persistence">Cache, Persistence and Files Settings</a>
</dt>
<dt>SET TIME ZONE, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>SET TRANSACTION, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>SHUTDOWN, <a class="indexterm" href="#mtc_system_operations">System Operations</a>
</dt>
<dt>SIGNAL STATEMENT, <a class="indexterm" href="#src_psm_exceptions">Raising Exceptions</a>
</dt>
<dt>SIGN function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>SIN function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>SORT_ARRAY function, <a class="indexterm" href="#bfc_array_functions">Array Functions</a>
</dt>
<dt>sort specification list, <a class="indexterm" href="#dac_ordering">Ordering</a>
</dt>
<dt>SOUNDEX function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>SPACE function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>SPECIFIC, <a class="indexterm" href="#dbc_common_elements">Common Elements and Statements</a>
</dt>
<dt>SPECIFIC NAME, <a class="indexterm" href="#src_routine_characteristics">Routine Characteristics</a>
</dt>
<dt>SQL_FEATURES, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>SQL_IMPLEMENTATION_INFO, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>SQL_PACKAGES, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>SQL_PARTS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>SQL_SIZING, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>SQL_SIZING_PROFILES, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>SQL DATA access characteristic, <a class="indexterm" href="#src_routine_characteristics">Routine Characteristics</a>
</dt>
<dt>SQL parameter reference, <a class="indexterm" href="#dac_sql_references">References, etc.</a>
</dt>
<dt>SQL procedure statement, <a class="indexterm" href="#dbc_procedure_satement">SQL Procedure Statement</a>
</dt>
<dt>SQL routine body, <a class="indexterm" href="#src_routine_definition">Routine Definition</a>
</dt>
<dt>SQRT function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>START TRANSACTION, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>string value expression, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
<dt>SUBSTR function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>SUBSTRING function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>SYSDATE function, <a class="indexterm" href="#bfc_current_datetime">Functions to Report the Current Datetime</a>
</dt>
<dt>SYSTEM_BESTROWIDENTIFIER, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_CACHEINFO, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_COLUMN_SEQUENCE_USAGE, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_COLUMNS, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_COMMENTS, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_CONNECTION_PROPERTIES, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_CROSSREFERENCE, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_INDEXINFO, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_PRIMARYKEYS, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_PROCEDURECOLUMNS, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_PROCEDURES, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_PROPERTIES, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_SCHEMAS, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_SEQUENCES, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_SESSIONINFO, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_SESSIONS, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_TABLES, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_TABLESTATS, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_TABLETYPES, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_TEXTTABLES, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_TYPEINFO, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_UDTS, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_USER function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>SYSTEM_USERS, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTEM_VERSIONCOLUMNS, <a class="indexterm" href="#dbc_hypersql_views_info_schema">HyperSQL Custom Views</a>
</dt>
<dt>SYSTIMESTAMP function, <a class="indexterm" href="#bfc_current_datetime">Functions to Report the Current Datetime</a>
</dt>
<dt>SYS USER, <a class="indexterm" href="#acc_built_in_roles_users">Built-In Roles and Users</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>T</h3>
<dl>
<dt>TABLE_CONSTRAINTS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>TABLE_PRIVILEGES, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>Table Function Derived Table, <a class="indexterm" href="#dac_table_function">Table Function Derived Table</a>
</dt>
<dt>TABLES, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>TAN function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>TIMESTAMP_WITH_ZONE function, <a class="indexterm" href="#bfc_datetime_format">Functions to Convert or Format a Datetime</a>
</dt>
<dt>TIMESTAMPADD function, <a class="indexterm" href="#bfc_datetime_arithmetic">Functions for Datetime Arithmetic</a>
</dt>
<dt>TIMESTAMPDIFF function, <a class="indexterm" href="#bfc_datetime_arithmetic">Functions for Datetime Arithmetic</a>
</dt>
<dt>TIMESTAMP function, <a class="indexterm" href="#bfc_datetime_format">Functions to Convert or Format a Datetime</a>
</dt>
<dt>Time Zone, <a class="indexterm" href="#sgc_datetime_types">Datetime types</a>
</dt>
<dt>TIMEZONE function, <a class="indexterm" href="#bfc_timezone_functions">Functions to Report the Time Zone.</a>
</dt>
<dt>TO_CHAR function, <a class="indexterm" href="#bfc_datetime_format">Functions to Convert or Format a Datetime</a>
</dt>
<dt>TO_DATE function, <a class="indexterm" href="#bfc_datetime_format">Functions to Convert or Format a Datetime</a>
</dt>
<dt>TO_NUMBER function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>TO_TIMESTAMP function, <a class="indexterm" href="#bfc_datetime_format">Functions to Convert or Format a Datetime</a>
</dt>
<dt>TODAY function, <a class="indexterm" href="#bfc_current_datetime">Functions to Report the Current Datetime</a>
</dt>
<dt>TRANSACTION_CONTROL function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>TRANSACTION_ID function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>TRANSACTION_SIZE function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>transaction characteristics, <a class="indexterm" href="#snc_statements">Session and Transaction Control Statements</a>
</dt>
<dt>TRANSLATE function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>TRANSLATIONS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>TRIGGER_COLUMN_USAGE, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>TRIGGER_ROUTINE_USAGE, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>TRIGGER_SEQUENCE_USAGE, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>TRIGGER_TABLE_USAGE, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>TRIGGERED_UPDATE_COLUMNS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>TRIGGERED SQL STATEMENT, <a class="indexterm" href="#trc_trigger_creation">Trigger Creation</a>
</dt>
<dt>TRIGGER EXECUTION ORDER, <a class="indexterm" href="#trc_trigger_creation">Trigger Creation</a>
</dt>
<dt>TRIGGERS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>TRIM_ARRAY function, <a class="indexterm" href="#bfc_array_functions">Array Functions</a>
</dt>
<dt>TRIM function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>TRUNCATE function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
<dt>TRUNCATE SCHEMA, <a class="indexterm" href="#dac_truncate_statement">Truncate Statement</a>
</dt>
<dt>TRUNCATE TABLE, <a class="indexterm" href="#dac_truncate_statement">Truncate Statement</a>
</dt>
<dt>TRUNC function datetime, <a class="indexterm" href="#bfc_datetime_arithmetic">Functions for Datetime Arithmetic</a>
</dt>
<dt>TRUNC function numeric, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>U</h3>
<dl>
<dt>UCASE function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>unicode escape elements, <a class="indexterm" href="#dac_literals">Literals</a>
</dt>
<dt>UNION JOIN, <a class="indexterm" href="#dac_joined_table">Joined Table</a>
</dt>
<dt>UNIQUE constraint, <a class="indexterm" href="#dbc_table_creation">Table Creation</a>
</dt>
<dt>UNIQUE predicate, <a class="indexterm" href="#dac_sql_predicates">Predicates</a>
</dt>
<dt>UNIX_TIMESTAMP function, <a class="indexterm" href="#bfc_extract_datetime">Functions to Extract an Element of a Datetime</a>
</dt>
<dt>UNNEST, <a class="indexterm" href="#dac_unnest">UNNEST</a>
</dt>
<dt>UPDATE, <a class="indexterm" href="#dac_update_statement">Update Statement</a>
</dt>
<dt>upgrading, <a class="indexterm" href="#dec_upgrade_database">Upgrading Databases</a>
</dt>
<dt>UPPER function, <a class="indexterm" href="#bfc_string_binary_functions">String and Binary String Functions</a>
</dt>
<dt>USAGE_PRIVILEGES, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>USER_DEFINED_TYPES, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>USER function, <a class="indexterm" href="#bfc_system_functions">System Functions</a>
</dt>
<dt>UUID function, <a class="indexterm" href="#bfc_general_functions">General Functions</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>V</h3>
<dl>
<dt>value expression, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
<dt>value expression primary, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
<dt>value specification, <a class="indexterm" href="#dac_value_expression">Value Expression</a>
</dt>
<dt>VIEW_COLUMN_USAGE, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>VIEW_ROUTINE_USAGE, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>VIEW_TABLE_USAGE, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
<dt>VIEWS, <a class="indexterm" href="#dbc_standard_views_info_schema">SQL Standard Views</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>W</h3>
<dl>
<dt>WEEK function, <a class="indexterm" href="#bfc_extract_datetime">Functions to Extract an Element of a Datetime</a>
</dt>
<dt>WHILE loop in routines, <a class="indexterm" href="#src_psm_iterated_statements">Iterated Statements</a>
</dt>
<dt>WIDTH_BUCKET function, <a class="indexterm" href="#bfc_numeric_functions">Numeric Functions</a>
</dt>
</dl>
</div>
<div class="indexdiv">
<h3>Y</h3>
<dl>
<dt>YEAR function, <a class="indexterm" href="#bfc_extract_datetime">Functions to Extract an Element of a Datetime</a>
</dt>
</dl>
</div>
</div>
</div>
</div>
<HR>
<P class="svnrev">$Revision: 5206 $</P>
</body>
</html>
